C API と ABI の安定性

特記のない限り、Python の C API には後方互換性ポリシー PEP 387 が適用されます。 変更の大半はソース互換性を保ちます (通常は新しい API の追加だけを行います)。 既存 API の変更や削除は、非推奨の期間を経た後、または重大な問題を修正するためにのみ行います。

CPython のアプリケーションバイナリインターフェース (ABI) は、同じマイナーリリース内で前方互換性と後方互換性を持ちます (同じ方法でコンパイルされている場合。下記の プラットフォームで考慮すべき点 を参照)。 したがって、Python 3.10.0 向けにコンパイルしたコードは 3.10.8 で動作し、その逆も同様ですが、3.9.x や 3.11.x 向けには別にコンパイルする必要があります。

C API には、期待される安定性が異なる二つの階層があります。

  • 不安定な API は、非推奨の期間なしにマイナーバージョン間で変更される可能性があります。 名前の接頭辞 PyUnstable で識別できます。

  • Limited API は、複数のマイナーリリースにわたって互換性を持ちます。 Py_LIMITED_API を定義すると、Python.h から公開されるのはこの部分集合だけになります。

以下でそれぞれを詳しく説明します。

_Py_InternalState のようにアンダースコアで始まる名前はプライベート API で、パッチリリースでも予告なく変更される可能性があります。 この API を使う必要がある場合は、CPython 開発者 に連絡し、用途に合う公開 API の追加を相談することを検討してください。

不安定な C API

接頭辞 PyUnstable を持つ API は CPython の実装の詳細を公開しており、マイナーリリースごとに (例えば 3.9 から 3.10 で) 非推奨の警告なしに変更される可能性があります。 ただし、バグ修正リリース (例えば 3.10.0 から 3.10.1) では変更されません。

通常はデバッガのような、低レベルの専門的なツールを対象としています。

この API を使うプロジェクトには、CPython の開発を追い、変更への対応に追加の労力をかけることが期待されます。

安定したアプリケーションバイナリインターフェース

Python の Stable ABI を使うと、再コンパイルせずに複数バージョンの Python と互換性を持つ拡張を作成できます。

注釈

説明を簡単にするため、この文書では 拡張 について述べますが、Python の組み込みなど、API のあらゆる用途で Stable ABI は同じように機能します。

Stable ABI は二つあります。

  • Python 3.2 で導入された abi3 は、CPython の フリースレッドビルド ではない ビルドと互換性を持ちます。

  • Python 3.15 で導入された abi3t は、CPython の フリースレッドビルド と互換性を持ちます。 abi3 より API の制約が厳しくなっています。

    Added in version 3.15: abi3t は PEP 803 で追加されました。

拡張を abi3 と abi3t の 両方 向けに同時にコンパイルすることもできます。 その結果は、フリースレッドビルドとそうでないビルドの両方で使えます。 現在のところ、abi3t だけを対象にコンパイルする場合と比べて不利な点はありません。

各 Stable ABI のバージョンには、Python のバージョンの最初の二つの数値を使います。 例えば Stable ABI 3.14 は Python 3.14 に対応します。 Stable ABI 3.x 向けにコンパイルした拡張は、Python 3.x 以降と ABI 互換性を持ちます。

Stable ABI を対象にする拡張は、C API の限定された部分集合だけを使わなければなりません。 この部分集合を Limited API と呼びます。 内容は 後述の一覧 を参照してください。

Windows では、Stable ABI を使う拡張は python39.dll のようなバージョン固有のライブラリではなく、python3.dll とリンクしてください。 このライブラリは、該当するシンボルだけを公開します。

一部のプラットフォームでは、Python は名前に abi3 または abi3t タグを持つ共有ライブラリファイル (例えば mymodule.abi3.so) を探して読み込みます。 フリースレッド のインタープリタは abi3t タグだけを認識し、それ以外のインタープリタは abi3 を優先しますが、なければ abi3t を使います。 したがって、両方の ABI と互換性のある拡張には abi3t タグを使ってください。

Python は、読み込む拡張の ABI に互換性があるかどうかを必ずしも確認しません。 拡張の作者には Py_mod_abi スロットまたは PyABIInfo_Check() 関数による確認を追加することが推奨されます。 ただし、例えば Stable ABI 3.10 向けの拡張をそれより古い Python にインストールしないようにする最終的な責任は、利用者 (またはパッケージ管理ツール) にあります。

Stable ABI のすべての関数は、マクロだけでなく Python の共有ライブラリ内の関数としても存在します。 このため、Python の ctypes を含め、C プリプロセッサを使わない言語からも利用できます。

Stable ABI 向けのコンパイル

注釈

meson-python、scikit-build-core、Setuptools などのビルドツールには、マクロを設定し、拡張のファイル名やほかのメタデータと同期させる仕組みがあることが多いです。 その仕組みがある場合は、手動でマクロを定義するよりもそちらを使ってください。

この節の残りは、主にツールの作者と手動で拡張をコンパイルする人に関係します。

参考

Python Packaging User Guide の 推奨ツールの一覧

Stable ABI 向けにコンパイルするには、以下のマクロの一方または両方を、拡張でサポートする最も古い Python バージョンに Py_PACK_VERSION 形式で定義します。 通常は、コンパイルに使う Python ヘッダのバージョンではなく、具体的な値を選んでください。

マクロは Python.h をインクルードする前に定義する必要があります。 この時点では Py_PACK_VERSION を使えないため、数値を直接使う必要があります。 参考として、最近の Python バージョンの値をいくつか示します。

0x30a0000  /* Py_PACK_VERSION(3,10) */
0x30b0000  /* Py_PACK_VERSION(3,11) */
0x30c0000  /* Py_PACK_VERSION(3,12) */
0x30d0000  /* Py_PACK_VERSION(3,13) */
0x30e0000  /* Py_PACK_VERSION(3,14) */
0x30f0000  /* Py_PACK_VERSION(3,15) */

どちらかのマクロを定義すると、Python.h は指定した Stable ABI と互換性のある API だけを公開します。 つまり Limited API と、コンパイラから見える必要はあっても直接使うべきでない一部の定義です。 両方を定義した場合は、両方の Stable ABI と互換性のある API だけを公開します。

Py_LIMITED_API

abi3、つまり CPython の フリースレッドビルド ではないビルドを対象にします。 共通の情報は 前述の説明 を参照してください。

Py_TARGET_ABI3T

abi3t、つまり CPython の フリースレッドビルド を対象にします。 共通の情報は 前述の説明 を参照してください。

Added in version 3.15.

どちらのマクロも対象の ABI を指定します。 名前の形式が異なるのは、後方互換性のためです。

歴史的な補足

Py_LIMITED_API を 3 と定義することもできます。 これは 0x03020000 (Stable ABI を導入した Python 3.2) と同じように機能します。

両方が定義されている場合、Python.h は Py_LIMITED_API を Py_TARGET_ABI3T に合わせて再定義する場合としない場合があります。

フリースレッドビルド、つまり Py_GIL_DISABLED が定義されている場合、Py_TARGET_ABI3T のデフォルトは Py_LIMITED_API の値です。 このため、abi3 と abi3t の両方を対象にビルドする方法は二つあります。

  • Py_LIMITED_API と Py_TARGET_ABI3T の両方を定義する、または

  • Py_LIMITED_API だけを定義し、さらに次を行う。

    • Windows では Py_GIL_DISABLED を定義する。

    • それ以外のシステムでは、Python のフリースレッドビルドのヘッダを使う。

Stable ABI の範囲と性能

Stable ABI の目標は、性能が低下する可能性はあるものの、完全な C API で可能なことをすべて可能にすることです。 一般に Stable ABI に対応するには、拡張のソースコードに多少の変更が必要です。

例えば PyList_GetItem() は利用できますが、「安全でない」マクロ版の PyList_GET_ITEM() は利用できません。 このマクロは、リストオブジェクトのバージョン固有の実装の詳細に依存できるため、高速な場合があります。

また、Stable ABI 向けにコンパイル しない 場合、一部の C API 関数はインライン展開されたりマクロに置き換えられたりします。 Stable ABI 向けのコンパイルではこのインライン展開を無効にするため、Python のデータ構造が改良されても安定性を保てますが、性能が低下する可能性があります。

Py_LIMITED_API または Py_TARGET_ABI3T の定義を省くと、Stable ABI 対応のソースをバージョン固有の ABI 向けにコンパイルできます。 その結果、性能が高くなる可能性のあるバージョン固有の拡張と、低速でも互換性の高い代替として Stable ABI 向けにコンパイルした版を、併せて配布できます。

Stable ABI の注意点

Stable ABI 向けにコンパイルしても、意図した Python バージョンでコードが動作する完全な保証には なりません。 Stable ABI は、シンボル不足によるリンクエラーや、構造体のレイアウトや関数シグネチャの変更によるデータ破損などの ABI の問題を防ぎます。 ただし、Python のほかの変更によって拡張の 動作 が変わることはあります。

Py_TARGET_ABI3T と Py_LIMITED_API で防げない問題の一つに、古い Python では無効な引数で関数を呼び出すことがあります。 例えば、ある関数が引数として NULL を受け取るようになった場合を考えてください。 Python 3.9 では NULL がデフォルトの動作を選択するのに、Python 3.8 では引数をそのまま使ってしまい、NULL の参照先へのアクセスによってクラッシュするかもしれません。 構造体のフィールドにも同様のことが言えます。

このため、拡張がサポートする すべて の Python マイナーバージョンでテストすることを推奨します。

また、使用するすべての API のドキュメントを確認し、それが明示的に Limited API の一部であるかどうかをチェックすることをお勧めします。Py_LIMITED_API が定義されていても、技術的な理由で(あるいはバグとして意図せず)いくつかのプライベート宣言が公開されることがあります。

また、Py_LIMITED_API を 3.8 にしてコンパイルした拡張は Python 3.12 で 読み込め、Python 3.12 で コンパイルできる はずですが、同じソースが Py_LIMITED_API を 3.12 にしてコンパイルできるとは限りません。 一般に、Stable ABI の安定性を維持する限り、Limited API の一部は非推奨になったり削除されたりすることがあります。

プラットフォームで考慮すべき点

ABI の安定性は Python だけでなく、使用するコンパイラ、低レベルのライブラリ、コンパイラオプションにも依存します。 Stable ABI では、これらの詳細をまとめて「プラットフォーム」と呼びます。 通常は OS の種類とプロセッサのアーキテクチャによって決まります。

特定のプラットフォーム上のすべての Python バージョンが、Stable ABI やバージョン固有の ABI の互換性を壊さない方法でビルドされるようにするのは、それぞれの Python 配布者の責任です。 python.org の Windows 版と macOS 版、および多くのサードパーティの配布者はこれを行っています。

ABI の確認

Added in version 3.15.

Python は ABI 互換性の基本的な確認機能を備えています。

この確認は網羅的ではありません。 互換性のないモジュールが誤ったインタープリタ向けにインストールされる、よくある場合だけを防ぎます。 プラットフォームの非互換性 も考慮しません。 確認できるのは、拡張の読み込みに成功した後だけです。

このような制限はありますが、検出できる非互換性によってクラッシュする代わりに例外を送出できるよう、拡張モジュールではこの仕組みを使うことを推奨します。

ほとんどのモジュールでは、Py_mod_abi スロットと PyABIInfo_VAR マクロを使って、例えば次のように確認できます。

PyABIInfo_VAR(abi_info);

static PyModuleDef_Slot mymodule_slots[] = {
   {Py_mod_abi, &abi_info},
   ...
};

高度な用途向けに、以下で API 全体を説明します。

int PyABIInfo_Check(PyABIInfo *info, const char *module_name)
次に属します: Stable ABI (バージョン 3.15 より).

指定された info が、現在実行中のインタープリタと互換性があるかどうかを確認します。

成功した場合は 0 を返します。 失敗した場合は例外を送出し、-1 を返します。

ABI に互換性がない場合、送出する例外は ImportError です。

module_name 引数は NULL、またはエラーメッセージに使う NUL 終端の UTF-8 エンコード文字列へのポインタです。

Note that if info describes the ABI that the current code uses (as defined by PyABIInfo_VAR, for example), using any other Python C API may lead to crashes. In particular, it is not safe to examine the raised exception.

Added in version 3.15.

PyABIInfo_VAR(NAME)
This macro is available when compiling for the Stable ABI (バージョン 3.15 より).

指定された名前 NAME で、現在のコードが使う ABI を記述する静的な PyABIInfo 変数を定義します。 このマクロは次のように展開されます。

static PyABIInfo NAME = {
    1, 0,
    PyABIInfo_DEFAULT_FLAGS,
    PY_VERSION_HEX,
    PyABIInfo_DEFAULT_ABI_VERSION
}

Added in version 3.15.

type PyABIInfo
次に属します: Stable ABI (すべてのメンバーを含む) (バージョン 3.15 より).
uint8_t abiinfo_major_version

PyABIInfo のメジャーバージョン。 次の値を設定できます。

  • 0: すべての確認を省略する、または

  • 1: このバージョンの PyABIInfo を指定する。

uint8_t abiinfo_minor_version

PyABIInfo のマイナーバージョン。 0 に設定する必要があります。 それより大きな値は、将来の後方互換性を持つ PyABIInfo のバージョン用に予約されています。

uint16_t flags

通常、このフィールドには次のマクロを設定します。

PyABIInfo_DEFAULT_FLAGS
次に属します: Stable ABI (バージョン 3.15 より).

Py_LIMITED_API や Py_GIL_DISABLED などのマクロの現在の値に基づく、デフォルトのフラグです。

または、以下のフラグをビット OR で組み合わせて設定できます。 未使用のビットはゼロにする必要があります。

ABI の種類。次のいずれかです。

PyABIInfo_STABLE
次に属します: Stable ABI (バージョン 3.15 より).

Stable ABI を使うことを指定します。

PyABIInfo_INTERNAL

CPython の特定のビルドに固有の ABI を指定します。 内部専用です。

フリースレッド対応。次のいずれかです。

PyABIInfo_FREETHREADED
次に属します: Stable ABI (バージョン 3.15 より).

CPython の フリースレッドビルド と互換性のある ABI を指定します。 つまり --disable-gil でコンパイルされ、sys.abiflags に t があるビルドです。

PyABIInfo_GIL
次に属します: Stable ABI (バージョン 3.15 より).

CPython のフリースレッドでないビルド (--disable-gil を指定 せずに コンパイルしたもの) と互換性のある ABI を指定します。

PyABIInfo_FREETHREADING_AGNOSTIC
次に属します: Stable ABI (バージョン 3.15 より).

CPython のフリースレッドビルドとそれ以外のビルドの両方、つまり abi3 と abi3t の両方と互換性のある ABI を指定します。

uint32_t build_version

コードのビルドに使った Python ヘッダのバージョンを、PY_VERSION_HEX と同じ形式で指定します。

0 に設定すると、このフィールドに関する確認をすべて省略できます。 主に、CPython ヘッダを直接使わず、特定バージョンのヘッダをエミュレートもしないプロジェクト向けの設定です。

uint32_t abi_version

ABI のバージョン。

Stable ABI では、このフィールドを Py_LIMITED_API または Py_TARGET_ABI3T の値に設定します。 両方が定義されている場合は小さい方を使います。 (Py_LIMITED_API が 3 の場合は、3 の代わりに Py_PACK_VERSION(3, 2) を使ってください。)

それ以外の場合は PY_VERSION_HEX に設定します。

0 に設定して、このフィールドに関する確認をすべて省略することもできます。

PyABIInfo_DEFAULT_ABI_VERSION
次に属します: Stable ABI (バージョン 3.15 より).

Py_LIMITED_API、PY_VERSION_HEX、Py_GIL_DISABLED などのマクロの現在の値に基づき、このフィールドに使うべき値を示します。

Added in version 3.15.

限定版APIの内容

Python 3.15 の Limited API の正式な一覧です。