Doc/c-api/apiabiversion.rst

.. highlight:: c

.. _apiabiversion:

***********************
API and ABI Versioning
***********************


Build-time version constants
----------------------------

CPython exposes its version number in the following macros.
Note that these correspond to the version code is **built** with.
See :c:var:`Py_Version` for the version used at **run time**.

See :ref:`stable` for a discussion of API and ABI stability across versions.

.. c:macro:: PY_MAJOR_VERSION

   The ``3`` in ``3.4.1a2``.

.. c:macro:: PY_MINOR_VERSION

   The ``4`` in ``3.4.1a2``.

.. c:macro:: PY_MICRO_VERSION

   The ``1`` in ``3.4.1a2``.

.. c:macro:: PY_RELEASE_LEVEL

   The ``a`` in ``3.4.1a2``.
   This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release
   candidate or ``0xF`` for final.


   .. c:namespace:: NULL
   .. c:macro:: PY_RELEASE_LEVEL_ALPHA
      :no-typesetting:
   .. c:macro:: PY_RELEASE_LEVEL_BETA
      :no-typesetting:
   .. c:macro:: PY_RELEASE_LEVEL_GAMMA
      :no-typesetting:
   .. c:macro:: PY_RELEASE_LEVEL_FINAL
      :no-typesetting:

   For completeness, the values are available as macros:
   :c:macro:`!PY_RELEASE_LEVEL_ALPHA` (``0xA``),
   :c:macro:`!PY_RELEASE_LEVEL_BETA` (``0xB``),
   :c:macro:`!PY_RELEASE_LEVEL_GAMMA` (``0xC``), and
   :c:macro:`!PY_RELEASE_LEVEL_FINAL` (``0xF``).

.. c:macro:: PY_RELEASE_SERIAL

   The ``2`` in ``3.4.1a2``. Zero for final releases.

.. c:macro:: PY_VERSION_HEX

   The Python version number encoded in a single integer.
   See :c:func:`Py_PACK_FULL_VERSION` for the encoding details.

   Use this for numeric comparisons, for example,
   ``#if PY_VERSION_HEX >= ...``.

.. c:macro:: PY_VERSION

   The Python version as a string, for example, ``"3.4.1a2"``.

These macros are defined in :source:`Include/patchlevel.h`.


Run-time version
----------------

.. c:var:: const unsigned long Py_Version

   The Python runtime version number encoded in a single constant integer.
   See :c:func:`Py_PACK_FULL_VERSION` for the encoding details.
   This contains the Python version used at run time.

   Use this for numeric comparisons, for example, ``if (Py_Version >= ...)``.

   .. versionadded:: 3.11


Bit-packing macros
------------------

.. c:function:: uint32_t Py_PACK_FULL_VERSION(int major, int minor, int micro, int release_level, int release_serial)

   Return the given version, encoded as a single 32-bit integer with
   the following structure:

   +------------------+-------+----------------+-----------+--------------------------+
   |                  | No.   |                |           | Example values           |
   |                  | of    |                |           +-------------+------------+
   | Argument         | bits  | Bit mask       | Bit shift | ``3.4.1a2`` | ``3.10.0`` |
   +==================+=======+================+===========+=============+============+
   | *major*          |   8   | ``0xFF000000`` | 24        | ``0x03``    | ``0x03``   |
   +------------------+-------+----------------+-----------+-------------+------------+
   | *minor*          |   8   | ``0x00FF0000`` | 16        | ``0x04``    | ``0x0A``   |
   +------------------+-------+----------------+-----------+-------------+------------+
   | *micro*          |   8   | ``0x0000FF00`` | 8         | ``0x01``    | ``0x00``   |
   +------------------+-------+----------------+-----------+-------------+------------+
   | *release_level*  |   4   | ``0x000000F0`` | 4         | ``0xA``     | ``0xF``    |
   +------------------+-------+----------------+-----------+-------------+------------+
   | *release_serial* |   4   | ``0x0000000F`` | 0         | ``0x2``     | ``0x0``    |
   +------------------+-------+----------------+-----------+-------------+------------+

   For example:

   +-------------+------------------------------------+-----------------+
   | Version     | ``Py_PACK_FULL_VERSION`` arguments | Encoded version |
   +=============+====================================+=================+
   | ``3.4.1a2`` | ``(3, 4, 1, 0xA, 2)``              | ``0x030401a2``  |
   +-------------+------------------------------------+-----------------+
   | ``3.10.0``  | ``(3, 10, 0, 0xF, 0)``             | ``0x030a00f0``  |
   +-------------+------------------------------------+-----------------+

   Out-of range bits in the arguments are ignored.
   That is, the macro can be defined as:

   .. code-block:: c

      #ifndef Py_PACK_FULL_VERSION
      #define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \
         (((X) & 0xff) << 24) |                              \
         (((Y) & 0xff) << 16) |                              \
         (((Z) & 0xff) << 8) |                               \
         (((LEVEL) & 0xf) << 4) |                            \
         (((SERIAL) & 0xf) << 0))
      #endif

   ``Py_PACK_FULL_VERSION`` is primarily a macro, intended for use in
   ``#if`` directives, but it is also available as an exported function.

   .. versionadded:: 3.14

.. c:function:: uint32_t Py_PACK_VERSION(int major, int minor)

   Equivalent to ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)``.
   The result does not correspond to any Python release, but is useful
   in numeric comparisons.

   .. versionadded:: 3.14