C API 穩定性

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

CPython's Application Binary Interface (ABI) is forward- and backwards-compatible across a minor release (if these are compiled the same way; see 平台注意事項 below). So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa, but will need to be compiled separately for 3.9.x and 3.11.x.

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

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

For simplicity, this document talks about extensions, but the Limited API and Stable ABI work the same way for all uses of the API – for example, embedding Python.

Limited C API

Python 3.2 introduced the Limited API, a subset of Python's C API. Extensions that only use the Limited API can be compiled once and work with multiple versions of Python. Contents of the Limited API are listed below.

Py_LIMITED_API

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

Define Py_LIMITED_API to the value of PY_VERSION_HEX corresponding to the lowest Python version your extension supports. The extension will work without recompilation with all Python 3 releases from the specified one onward, and can use Limited API introduced up to that version.

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

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

Stable ABI

To enable this, Python provides a Stable ABI: a set of symbols that will remain compatible across Python 3.x versions.

The Stable ABI contains symbols exposed in the Limited API, but also other ones – for example, functions necessary to support older versions of the Limited 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 注意事項

Note that compiling with Py_LIMITED_API is not a complete guarantee that code conforms to the Limited API or the Stable ABI. Py_LIMITED_API only covers definitions, but an API also includes other issues, such as expected semantics.

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 stability depends not only on Python, but also on the compiler used, lower-level libraries and compiler options. For the purposes of the Stable ABI, these details define a “platform”. They usually depend on the OS type and processor architecture

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

受限 API 的內容

Currently, the Limited API includes the following items: