API と ABI のバージョニング
***************************


ビルド時のバージョン定数
========================

CPython は以下のマクロでバージョン番号を公開しています。 これらはコー
ドの **ビルド時** のバージョンに対応します。 **実行時** のバージョンに
ついては "Py_Version" を参照してください。

バージョン間の API と ABI の安定性については C API と ABI の安定性 を
参照してください。

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" 、ベータでは "0xB" 、リリース
   候補では "0xC" 、最終版では "0xF" となります。

   これらの値には対応するマクロもあります。 "PY_RELEASE_LEVEL_ALPHA"
   ("0xA")、"PY_RELEASE_LEVEL_BETA" ("0xB")、"PY_RELEASE_LEVEL_GAMMA"
   ("0xC")、"PY_RELEASE_LEVEL_FINAL" ("0xF") です。

PY_RELEASE_SERIAL

   "3.4.1a2" の "2" 。最終リリースでは 0 になります。

PY_VERSION_HEX

   Python のバージョン番号を一つの整数にエンコードした値です。 エンコ
   ードの詳細は "Py_PACK_FULL_VERSION()" を参照してください。

   "#if PY_VERSION_HEX >= ..." のように、数値として比較するときに使い
   ます。

PY_VERSION

   Python のバージョンを表す文字列です。 例えば ""3.4.1a2"" です。

これらのマクロは Include/patchlevel.h で定義されています。


実行時のバージョン
==================

const unsigned long Py_Version
    * 次に属します: Stable ABI (バージョン 3.11 より).*

   Python ランタイムのバージョン番号を一つの整数定数にエンコードした値
   です。 エンコードの詳細は "Py_PACK_FULL_VERSION()" を参照してくださ
   い。 実行時に使われている Python のバージョンを表します。

   "if (Py_Version >= ...)" のように、数値として比較するときに使います
   。

   Added in version 3.11.


ビットを詰め合わせるマクロ
==========================

uint32_t Py_PACK_FULL_VERSION(int major, int minor, int micro, int release_level, int release_serial)
    * 次に属します: Stable ABI (バージョン 3.14 より).*

   指定されたバージョンを、以下の構造を持つ一つの 32 ビット整数にエン
   コードして返します。

   +--------------------+---------+------------------+-------------+---------------+--------------+
   | 引数               | ビット  | ビットマスク     | ビットシフ  | 値の例                       |
   |                    | 数      |                  | ト          |                              |
   |                    |         |                  |             +---------------+--------------+
   |                    |         |                  |             | "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" の引数        | エンコードされた  |
   |               |                                      | バージョン        |
   |===============|======================================|===================|
   | "3.4.1a2"     | "(3, 4, 1, 0xA, 2)"                  | "0x030401a2"      |
   +---------------+--------------------------------------+-------------------+
   | "3.10.0"      | "(3, 10, 0, 0xF, 0)"                 | "0x030a00f0"      |
   +---------------+--------------------------------------+-------------------+

   引数の範囲外のビットは無視します。 つまり、このマクロは次のように定
   義できます。

      #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" は主に "#if" ディレクティブで使うためのマク
   ロですが、エクスポートされた関数としても利用できます。

   Added in version 3.14.

uint32_t Py_PACK_VERSION(int major, int minor)
    * 次に属します: Stable ABI (バージョン 3.14 より).*

   "Py_PACK_FULL_VERSION(major, minor, 0, 0, 0)" と同等です。 結果は実
   際の Python リリースには対応しませんが、数値による比較に便利です。

   Added in version 3.14.
