| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _apiabiversion: |
| 4 |
|
| 5 |
*********************** |
| 6 |
API and ABI Versioning |
| 7 |
*********************** |
| 8 |
|
| 9 |
|
| 10 |
Build-time version constants |
| 11 |
---------------------------- |
| 12 |
|
| 13 |
CPython exposes its version number in the following macros. |
| 14 |
Note that these correspond to the version code is **built** with. |
| 15 |
See :c:var:`Py_Version` for the version used at **run time**. |
| 16 |
|
| 17 |
See :ref:`stable` for a discussion of API and ABI stability across versions. |
| 18 |
|
| 19 |
.. c:macro:: PY_MAJOR_VERSION |
| 20 |
|
| 21 |
The ``3`` in ``3.4.1a2``. |
| 22 |
|
| 23 |
.. c:macro:: PY_MINOR_VERSION |
| 24 |
|
| 25 |
The ``4`` in ``3.4.1a2``. |
| 26 |
|
| 27 |
.. c:macro:: PY_MICRO_VERSION |
| 28 |
|
| 29 |
The ``1`` in ``3.4.1a2``. |
| 30 |
|
| 31 |
.. c:macro:: PY_RELEASE_LEVEL |
| 32 |
|
| 33 |
The ``a`` in ``3.4.1a2``. |
| 34 |
This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release |
| 35 |
candidate or ``0xF`` for final. |
| 36 |
|
| 37 |
.. c:macro:: PY_RELEASE_SERIAL |
| 38 |
|
| 39 |
The ``2`` in ``3.4.1a2``. Zero for final releases. |
| 40 |
|
| 41 |
.. c:macro:: PY_VERSION_HEX |
| 42 |
|
| 43 |
The Python version number encoded in a single integer. |
| 44 |
See :c:func:`Py_PACK_FULL_VERSION` for the encoding details. |
| 45 |
|
| 46 |
Use this for numeric comparisons, for example, |
| 47 |
``#if PY_VERSION_HEX >= ...``. |
| 48 |
|
| 49 |
These macros are defined in :source:`Include/patchlevel.h`. |
| 50 |
|
| 51 |
|
| 52 |
Run-time version |
| 53 |
---------------- |
| 54 |
|
| 55 |
.. c:var:: const unsigned long Py_Version |
| 56 |
|
| 57 |
The Python runtime version number encoded in a single constant integer. |
| 58 |
See :c:func:`Py_PACK_FULL_VERSION` for the encoding details. |
| 59 |
This contains the Python version used at run time. |
| 60 |
|
| 61 |
Use this for numeric comparisons, for example, ``if (Py_Version >= ...)``. |
| 62 |
|
| 63 |
.. versionadded:: 3.11 |
| 64 |
|
| 65 |
|
| 66 |
Bit-packing macros |
| 67 |
------------------ |
| 68 |
|
| 69 |
.. c:function:: uint32_t Py_PACK_FULL_VERSION(int major, int minor, int micro, int release_level, int release_serial) |
| 70 |
|
| 71 |
Return the given version, encoded as a single 32-bit integer with |
| 72 |
the following structure: |
| 73 |
|
| 74 |
+------------------+-------+----------------+-----------+--------------------------+ |
| 75 |
| | No. | | | Example values | |
| 76 |
| | of | | +-------------+------------+ |
| 77 |
| Argument | bits | Bit mask | Bit shift | ``3.4.1a2`` | ``3.10.0`` | |
| 78 |
+==================+=======+================+===========+=============+============+ |
| 79 |
| *major* | 8 | ``0xFF000000`` | 24 | ``0x03`` | ``0x03`` | |
| 80 |
+------------------+-------+----------------+-----------+-------------+------------+ |
| 81 |
| *minor* | 8 | ``0x00FF0000`` | 16 | ``0x04`` | ``0x0A`` | |
| 82 |
+------------------+-------+----------------+-----------+-------------+------------+ |
| 83 |
| *micro* | 8 | ``0x0000FF00`` | 8 | ``0x01`` | ``0x00`` | |
| 84 |
+------------------+-------+----------------+-----------+-------------+------------+ |
| 85 |
| *release_level* | 4 | ``0x000000F0`` | 4 | ``0xA`` | ``0xF`` | |
| 86 |
+------------------+-------+----------------+-----------+-------------+------------+ |
| 87 |
| *release_serial* | 4 | ``0x0000000F`` | 0 | ``0x2`` | ``0x0`` | |
| 88 |
+------------------+-------+----------------+-----------+-------------+------------+ |
| 89 |
|
| 90 |
For example: |
| 91 |
|
| 92 |
+-------------+------------------------------------+-----------------+ |
| 93 |
| Version | ``Py_PACK_FULL_VERSION`` arguments | Encoded version | |
| 94 |
+=============+====================================+=================+ |
| 95 |
| ``3.4.1a2`` | ``(3, 4, 1, 0xA, 2)`` | ``0x030401a2`` | |
| 96 |
+-------------+------------------------------------+-----------------+ |
| 97 |
| ``3.10.0`` | ``(3, 10, 0, 0xF, 0)`` | ``0x030a00f0`` | |
| 98 |
+-------------+------------------------------------+-----------------+ |
| 99 |
|
| 100 |
Out-of range bits in the arguments are ignored. |
| 101 |
That is, the macro can be defined as: |
| 102 |
|
| 103 |
.. code-block:: c |
| 104 |
|
| 105 |
#ifndef Py_PACK_FULL_VERSION |
| 106 |
#define Py_PACK_FULL_VERSION(X, Y, Z, LEVEL, SERIAL) ( \ |
| 107 |
(((X) & 0xff) << 24) | \ |
| 108 |
(((Y) & 0xff) << 16) | \ |
| 109 |
(((Z) & 0xff) << 8) | \ |
| 110 |
(((LEVEL) & 0xf) << 4) | \ |
| 111 |
(((SERIAL) & 0xf) << 0)) |
| 112 |
#endif |
| 113 |
|
| 114 |
``Py_PACK_FULL_VERSION`` is primarily a macro, intended for use in |
| 115 |
``#if`` directives, but it is also available as an exported function. |
| 116 |
|
| 117 |
.. versionadded:: 3.14 |
| 118 |
|
| 119 |
.. c:function:: uint32_t Py_PACK_VERSION(int major, int minor) |
| 120 |
|
| 121 |
Equivalent to ``Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)``. |
| 122 |
The result does not correspond to any Python release, but is useful |
| 123 |
in numeric comparisons. |
| 124 |
|
| 125 |
.. versionadded:: 3.14 |