python_doc_md/Advanced/c-api/apiabiversion.md

API and ABI Versioning {#apiabiversion}

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 Py_Version{.interpreted-text role="c:var"} for the version used at run time.

See stable{.interpreted-text role="ref"} for a discussion of API and ABI stability across versions.

The 3 in 3.4.1a2.

The 4 in 3.4.1a2.

The 1 in 3.4.1a2.

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

For completeness, the values are available as macros: !PY_RELEASE_LEVEL_ALPHA{.interpreted-text role="c:macro"} (0xA), !PY_RELEASE_LEVEL_BETA{.interpreted-text role="c:macro"} (0xB), !PY_RELEASE_LEVEL_GAMMA{.interpreted-text role="c:macro"} (0xC), and !PY_RELEASE_LEVEL_FINAL{.interpreted-text role="c:macro"} (0xF).

The 2 in 3.4.1a2. Zero for final releases.

The Python version number encoded in a single integer. See Py_PACK_FULL_VERSION{.interpreted-text role="c:func"} for the encoding details.

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

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

These macros are defined in Include/patchlevel.h{.interpreted-text role="source"}.

Run-time version

The Python runtime version number encoded in a single constant integer. See Py_PACK_FULL_VERSION{.interpreted-text role="c:func"} 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

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

+------------------+-------------+--------------+-----------+-------------------------+ | Argument | No. of bits | Bit mask | Bit shift | Example values | | | | | +------------+------------+ | | | | | 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:

#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 :::

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 :::