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