Spaces:
Running on Zero
Running on Zero
| # 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: | |
| > | |
| > ``` 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 | |
| > ::: | |
| > 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 | |
| > ::: | |