CAPIの安定性
PythonのCAPIは、下位互換性ポリシー PEP 387 でカバーされています。 C APIはマイナーリリースごとに変更されますが（例： 3.9から3.10）では、ほとんどの変更はソース互換であり、通常は新しいAPIを追加するだけです。 既存のAPIの変更またはAPIの削除は、非推奨期間の後、または重大な問題を修正するためにのみ行われます。
CPythonのアプリケーションバイナリインターフェイス（ABI）は、マイナーリリース全体で下位互換性と下位互換性があります（これらが同じ方法でコンパイルされている場合。以下のプラットフォームの考慮事項を参照してください）。 したがって、Python 3.10.0用にコンパイルされたコードは3.10.8で動作し、その逆も同様ですが、3.9.xと3.10.x用に別々にコンパイルする必要があります。
_Py_InternalStateなど、アンダースコアが前に付いた名前は、パッチリリースでも予告なしに変更される可能性のあるプライベートAPIです。
安定したアプリケーションバイナリインターフェイス
Python 3.2では、PythonのCAPIのサブセットである Limited API が導入されました。 Limited APIのみを使用する拡張機能は、一度コンパイルすれば、複数のバージョンのPythonで機能します。 Limited APIの内容は、以下のにリストされています。
これを有効にするために、Pythonは Stable ABI を提供します。これは、Python3.xバージョン間で互換性を維持する一連のシンボルです。 Stable ABIには、Limited APIで公開されているシンボルだけでなく、他のシンボルも含まれています。たとえば、LimitedAPIの古いバージョンをサポートするために必要な関数です。
（簡単にするために、このドキュメントでは拡張機能について説明していますが、制限付きAPIと安定したABIは、Pythonの埋め込みなど、APIのすべての使用で同じように機能します。）
- Py_LIMITED_API
Python.hを含める前にこのマクロを定義して、限定APIのみを使用するようにオプトインし、限定APIバージョンを選択します。Py_LIMITED_APIを、拡張機能がサポートする最も低いPythonバージョンに対応する PY_VERSION_HEX の値に定義します。 拡張機能は、指定されたもの以降のすべてのPython 3リリースで再コンパイルせずに機能し、そのバージョンまでに導入された限定APIを使用できます。PY_VERSION_HEXマクロを直接使用するのではなく、最小のマイナーバージョンをハードコーディングします（例：0x030A0000for Python 3.10）将来のPythonバージョンでコンパイルするときの安定性。Py_LIMITED_APIから3を定義することもできます。 これは、0x03020000（Python 3.2、限定APIを導入したバージョン）と同じように機能します。
Windowsでは、Stable ABIを使用する拡張機能は、python39.dllなどのバージョン固有のライブラリではなく、python3.dllに対してリンクする必要があります。
一部のプラットフォームでは、Pythonはabi3タグで名前が付けられた共有ライブラリファイルを検索してロードします（例： mymodule.abi3.so）。 このような拡張機能がStableABIに準拠しているかどうかはチェックされません。 ユーザー（またはそのパッケージングツール）は、たとえば、3.10以降の制限付きAPIで構築された拡張機能が下位バージョンのPythonにインストールされていないことを確認する必要があります。
Stable ABIのすべての関数は、マクロとしてだけでなく、Pythonの共有ライブラリに関数として存在します。 これにより、Cプリプロセッサを使用しない言語から使用できるようになります。
限られたAPIの範囲とパフォーマンス
Limited APIの目標は、完全なC APIで可能なすべてのことを可能にすることですが、パフォーマンスが低下する可能性があります。
たとえば、 PyList_GetItem（）は使用できますが、その「安全でない」マクロバリアント PyList_GET_ITEM（）は使用できません。 マクロは、リストオブジェクトのバージョン固有の実装の詳細に依存できるため、より高速になります。
Py_LIMITED_APIが定義されていない場合、一部のC API関数はインライン化されるか、マクロに置き換えられます。 Py_LIMITED_APIを定義すると、このインライン化が無効になり、Pythonのデータ構造が改善されても安定性が得られますが、パフォーマンスが低下する可能性があります。
Py_LIMITED_APIの定義を省略することで、バージョン固有のABIを使用して制限付きAPI拡張機能をコンパイルできます。 これにより、そのPythonバージョンのパフォーマンスが向上しますが、互換性が制限されます。 Py_LIMITED_APIを使用してコンパイルすると、バージョン固有の拡張機能が利用できない場合に配布できる拡張機能が生成されます。たとえば、次のPythonバージョンのプレリリースなどです。
限定されたAPIの警告
Py_LIMITED_APIを使用したコンパイルは、ではなく、コードがLimitedAPIまたはStableABIに準拠していることを完全に保証するものではないことに注意してください。 Py_LIMITED_APIは定義のみを対象としていますが、APIには、予想されるセマンティクスなどの他の問題も含まれています。
Py_LIMITED_APIが保護しない問題の1つは、Pythonの下位バージョンでは無効な引数を使用して関数を呼び出すことです。 たとえば、引数としてNULLの受け入れを開始する関数について考えてみます。 Python 3.9では、NULLがデフォルトの動作を選択するようになりましたが、Python 3.8では、引数が直接使用されるため、NULLの逆参照とクラッシュが発生します。 同様の引数が構造体のフィールドに対して機能します。
もう1つの問題は、Py_LIMITED_APIが定義されている場合、一部の構造体フィールドは、制限付きAPIの一部であるにもかかわらず、現在非表示になっていないことです。
これらの理由から、サポートするすべてのマイナーPythonバージョンで拡張機能をテストすることをお勧めします。できれば、そのようなバージョンの最低でビルドすることをお勧めします。
また、使用されているすべてのAPIのドキュメントを確認して、それが明示的にLimitedAPIの一部であるかどうかを確認することをお勧めします。 Py_LIMITED_APIが定義されていても、技術的な理由で（または、意図せずにバグとして）、いくつかのプライベート宣言が公開されています。
また、LimitedAPIは必ずしも安定しているとは限りません。Python3.8でPy_LIMITED_APIを使用してコンパイルすると、拡張機能はPython 3.12で実行されますが、Python3.12でコンパイルを実行するとは限りません。 特に、Stable ABIが安定している場合は、LimitedAPIの一部が非推奨になり削除される可能性があります。
プラットフォームに関する考慮事項
ABIの安定性は、Pythonだけでなく、使用するコンパイラ、低レベルのライブラリ、およびコンパイラオプションにも依存します。 安定したABIの目的のために、これらの詳細は「プラットフォーム」を定義します。 それらは通常、OSのタイプとプロセッサアーキテクチャに依存します
特定のプラットフォーム上のすべてのPythonバージョンが、Stable ABIを壊さない方法で構築されていることを確認するのは、Pythonの各特定のディストリビューターの責任です。 これは、python.orgおよび多くのサードパーティディストリビューターからのWindowsおよびmacOSリリースの場合です。
限定APIの内容
現在、LimitedAPIには次のアイテムが含まれています。
