Debian Codegraph @

Doc/c-api/apiabiversion.rst

raw
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