C API 穩定性

Python 的 C API 被包含在向後相容性策略 PEP 387 中。雖然 C API 會隨著每個次要版本（例如從 3.9 到 3.10）而變化，但大多數變化都是與原始碼相容的，通常只是加入新的 API。更改現有 API 或刪除 API 僅在棄用期後或修復嚴重問題時進行。

CPython 的应用程序二进制接口（ABI）可以跨微版本向上和向下兼容（在以相同方式编译的情况下，参见下文 平台注意事項 一节）。 因此，针对 Python 3.10.0 编译的代码将适用于 3.10.8，反之亦然，但对于 3.9.x 和 3.11.x 则需要单独编译。

帶有底線前綴的名稱是私有 API (private API)，像是 _Py_InternalState，即使在補丁版本 (patch release) 中也可能被更改，不會另行通知。

穩定的應用程式二進位介面

简单起见，本文档只讨论了 扩展，但受限 API 和稳定 ABI 对于 API 的所有用法都能发挥相同的作用 – 例如嵌入版的 Python 等。

受限 C API

Python 3.2 引入了 受限 API，它是 Python 的 C API 的一个子集。 只使用受限 API 扩展可以一次编译即适用于多个 Python 版本。 受限 API 的内容 如下所示。

Py_LIMITED_API

在包含 Python.h 之前定義此巨集以選擇只使用受限 API，並挑選受限 API 版本。

将 Py_LIMITED_API 定义为与你的扩展所支持的最低 Python 版本的 PY_VERSION_HEX 的值。 扩展将无需重编译即可适用于从该指定版本开始的所有 Python 3 发布版，并可使用到该版本为止所引入的受限 API。

與其直接使用 PY_VERSION_HEX 巨集，不如寫死 (hardcode) 最小次要版本（例如代表 Python 3.10 的 0x030A0000），以便在使用未來的 Python 版本進行編譯時仍保持穩定性。

你還可以將 Py_LIMITED_API 定義為 3，這與 0x03020000（Python 3.2，引入了受限 API 的版本）相同。

稳定 ABI

为启用此特性，Python 提供了一个 稳定 ABI: 将能跨 Python 3.x 版本保持兼容的一组符号。

稳定 ABI 包含在 受限 API 中对外公开的符号，但还包含其他符号 – 例如，为支持旧版本受限 API 所需的函数。

在 Windows 上，使用穩定 ABI 的擴充應該連接到 python3.dll 而不是特定版本的函式庫，例如 python39.dll。

在某些平台上，Python 將查找並加載以 abi3 標籤命名的共享函式庫檔案（例如 mymodule.abi3.so）。它不檢查此類擴充是否符合穩定的 ABI。確保的責任在使用者（或者打包工具）身上，例如使用 3.10+ 受限 API 建置的擴充不會為較低版本的 Python 所安裝。

穩定 ABI 中的所有函式都作為函式存在於 Python 的共享函式庫中，而不僅是作為巨集。這使得它們可被用於不使用 C 預處理器 (preprocessor) 的語言。

受限 API 範圍和性能

受限 API 的目標是允許使用完整的 C API 進行所有可能的操作，但可能會降低性能。

例如，雖然 PyList_GetItem() 可用，但它的「不安全」巨集變體 PyList_GET_ITEM() 為不可用。巨集運行可以更快，因為它可以依賴 list 物件的特定版本實作細節。

如果沒有定義 Py_LIMITED_API，一些 C API 函式將被嵌入或被替換為巨集。定義 Py_LIMITED_API 會禁用嵌入，從而隨著 Python 資料結構的改進而提高穩定性，但可能會降低性能。

通過省略 Py_LIMITED_API 定義，可以使用特定版本的 ABI 編譯受限 API 擴充。這可以提高該 Python 版本的性能，但會限制相容性。使用 Py_LIMITED_API 編譯將產生一個擴充，可以在特定版本的擴充不可用的地方發布 — 例如，用於即將發布的 Python 版本的預發布版本 (prerelease)。

受限 API 注意事項

请注意使用 Py_LIMITED_API 进行编译 无法 完全保证代码能够兼容 受限 API 或 稳定 ABI。 Py_LIMITED_API 仅仅涵盖定义部分，但一个 API 还包括其他因素，如预期的语义等。

Py_LIMITED_API 無法防範的一個問題是使用在較低 Python 版本中無效的引數來呼叫函式。例如一個開始接受 NULL 作為引數的函式。在 Python 3.9 中，NULL 現在代表選擇預設行為，但在 Python 3.8 中，引數將被直接使用，導致 NULL 取消參照 (dereference) 且崩潰 (crash)。類似的引數適用於結構 (struct) 的欄位。

另一個問題是，當有定義 Py_LIMITED_API 時，一些結構欄位目前不會被隱藏，即使它們是受限 API 的一部分。

出於這些原因，我們建議要以它支援的所有次要 Python 版本來測試擴充，並且最好使用最低版本進行建置。

我們也建議要查看所有使用過的 API 的文件，檢查它是否明確屬於受限 API。即使有定義 Py_LIMITED_API，一些私有聲明也會因為技術原因（或者甚至是無意地，例如臭蟲）而被公開出來。

另請注意，受限 API 不一定是穩定的：在 Python 3.8 中使用 Py_LIMITED_API 進行編譯意味著擴充將能以 Python 3.12 運行，但不一定能以 Python 3.12 編譯。特別是如果穩定 ABI 保持穩定，部分受限 API 可能會被棄用和刪除。

平台注意事項

ABI 的稳定性不仅取决于 Python，取决于所使用的编译器、低层级库和编译器选项等。 对于 稳定 ABI 的目标来说，这些细节定义了一个 “平台”。 它们通常会依赖于 OS 类型和处理器架构等。

每個特定的 Python 發布者都有責任確保特定平台上的所有 Python 版本都以不破壞穩定 ABI 的方式建置。python.org 和許多第三方發布者發布的 Windows 和 macOS 版本就是這種情況。

受限 API 的內容

目前 受限 API 包括下面这些项: