# API 和 ABI 版本管理

## Build-time version constants

CPython 透過以下巨集 (macro) 公開其版本號。請注意，對應到的是建置 (built) 所用到的版本。關於run time 所使用的版本，請見 `Py_Version`。

關於跨版本 API 和 ABI 穩定性的討論，請見 C API and ABI Stability。

PY_MAJOR_VERSION

  在 `3.4.1a2` 中的 `3`。

PY_MINOR_VERSION

  在 `3.4.1a2` 中的 `4`。

PY_MICRO_VERSION

  在 `3.4.1a2` 中的 `1`。

PY_RELEASE_LEVEL

  在 `3.4.1a2` 中的 `a`。`0xA` 代表 alpha 版本、`0xB` 代表 beta 版本、`0xC` 為發布候選版本、`0xF` 則為最終版。

  For completeness, the values are available as macros: `PY_RELEASE_LEVEL_ALPHA` (`0xA`), `PY_RELEASE_LEVEL_BETA` (`0xB`), `PY_RELEASE_LEVEL_GAMMA` (`0xC`), and `PY_RELEASE_LEVEL_FINAL` (`0xF`).

PY_RELEASE_SERIAL

  在 `3.4.1a2` 中的 `2`。零則為最終發布版本。

PY_VERSION_HEX

  被編碼為單一整數的 Python 版本號。詳見 `Py_PACK_FULL_VERSION()` 以了解編碼詳細資訊。

  使用它進行數值比較，例如 `#if PY_VERSION_HEX >= ...`。

PY_VERSION

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

These macros are defined in Include/patchlevel.h.

## Run-time version

const unsigned long Py_Version
  為 穩定 ABI 的一部分 自 3.11 版本開始.

  編碼為單個常數整數的 Python runtime 版本號。詳見 `Py_PACK_FULL_VERSION()` 以了解編碼詳細資訊。這包含在 runtime 使用的 Python 版本。

  使用它進行數值比較，例如 `if (Py_Version >= ...)`。

  在 3.11 版被加入.

## Bit-packing macros

uint32_t Py_PACK_FULL_VERSION(int major, int minor, int micro, int release_level, int release_serial)
  為 穩定 ABI 的一部分 自 3.14 版本開始.

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

  引數 | 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`

  例如：

  版本 | `Py_PACK_FULL_VERSION` 引數 | 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.

  在 3.14 版被加入.

uint32_t Py_PACK_VERSION(int major, int minor)
  為 穩定 ABI 的一部分 自 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.

  在 3.14 版被加入.