API 和 ABI 版本管理
*******************


Build-time version constants
============================

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

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

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" 則為最終版。

PY_RELEASE_SERIAL

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

PY_VERSION_HEX

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

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

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  | Bit mask         | Bit shift   | Example values               |
   |                    | bits    |                  |             |                              |
   |                    |         |                  |             +---------------+--------------+
   |                    |         |                  |             | "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 版被加入.
