GeezerVisonThe World Wide Web, restored to 800 pixels of glory. |
| Home|About|Gaming cabinet|Archives|How it works|Starter sites |
GeezerVison is showing docs.python.org — C API and ABI Stability C API and ABI Stability¶Unless documented otherwise, Python’s C API is covered by the Backwards Compatibility Policy, PEP 387. Most changes to it are source-compatible (typically by only adding new API). Changing existing API or removing API is only done after a deprecation period or to fix serious issues. CPython’s Application Binary Interface (ABI) is forward- and backwards-compatible across a minor release (if these are compiled the same way; see Platform Considerations 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. There are two tiers of C API with different stability expectations:
These are discussed in more detail below. Names prefixed by an underscore, such as Unstable C API¶Any API named with the It is generally intended for specialized, low-level tools like debuggers. Projects that use this API are expected to follow CPython development and spend extra effort adjusting to changes. Stable Application Binary Interfaces¶Python’s Stable ABI allows extensions to be compatible with multiple versions of Python, without recompilation. Note For simplicity, this document talks about extensions, but Stable ABI works the same way for all uses of the API – for example, embedding Python. There are two Stable ABIs:
It is possible for an extension to be compiled for both Each Stable ABI is versioned using the first two numbers of the Python version. For example, Stable ABI 3.14 corresponds to Python 3.14. An extension compiled for Stable ABI 3.x is ABI-compatible with Python 3.x and above. Extensions that target a stable ABI must only use a limited subset of the C API. This subset is known as the Limited API; its contents are listed below. On Windows, extensions that use a Stable ABI should be linked against
On some platforms, Python will look for and load shared library files named
with the Python does not necessarily check that extensions it loads
have compatible ABI.
Extension authors are encouraged to add a check using the All functions in Stable ABI are present as functions in Python’s shared
library, not solely as macros.
This makes them usable in languages that don’t use the C
preprocessor, including Python’s Compiling for Stable ABI¶Note Build tools (such as, for example, meson-python, scikit-build-core, or Setuptools) often have a mechanism for setting macros and synchronizing them with extension filenames and other metadata. Prefer using such a mechanism, if it exists, over defining the macros manually. The rest of this section is mainly relevant for tool authors, and for people who compile extensions manually. See also list of recommended tools in the Python Packaging User Guide To compile for a Stable ABI, define one or both of the following macros
to the lowest Python version your extension should support, in
The macros must be defined before including 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) */ 0x3100000 /* Py_PACK_VERSION(3,16) */ When one of the macros is defined,
Both macros specify a target ABI; the different naming style is due to backwards compatibility. Historical note You can also define When both are defined, On a free-threaded build – that is, when
Stable ABI Scope and Performance¶The goal for Stable ABI is to allow everything that is possible with the full C API, but possibly with a performance penalty. Generally, compatibility with Stable ABI will require some changes to an extension’s source code. For example, while For another example, when not compiling for Stable ABI, some C API functions are inlined or replaced by macros. Compiling for Stable ABI disables this inlining, allowing stability as Python’s data structures are improved, but possibly reducing performance. By leaving out the Stable ABI Caveats¶Note that compiling for Stable ABI is not a complete guarantee that code will be compatible with the expected Python versions. Stable ABI prevents ABI issues, like linker errors due to missing symbols or data corruption due to changes in structure layouts or function signatures. However, other changes in Python can change the behavior of extensions. One issue that the For these reasons, we recommend testing an extension with all minor Python versions it supports. We also recommend reviewing documentation of all used API to check
if it is explicitly part of the Limited API. Even with Also note that while compiling with Platform Considerations¶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 ABIs, these details define a “platform”. They usually depend on the OS type and processor architecture It is the responsibility of each particular distributor of Python
to ensure that all Python versions on a particular platform are built
in a way that does not break the Stable ABIs, or the version-specific ABIs.
This is the case with Windows and macOS releases from ABI Checking¶Added in version 3.15. Python includes a rudimentary check for ABI compatibility. This check is not comprehensive. It only guards against common cases of incompatible modules being installed for the wrong interpreter. It also does not take platform incompatibilities into account. It can only be done after an extension is successfully loaded. Despite these limitations, it is recommended that extension modules use this mechanism, so that detectable incompatibilities raise exceptions rather than crash. Most modules can use this check via the PyABIInfo_VAR(abi_info); static PyModuleDef_Slot mymodule_slots[] = { {Py_mod_abi, &abi_info}, ... }; The full API is described below for advanced use cases.
Contents of Limited API¶This is the definitive list of Limited API for Python 3.16:
© Copyright 2001 Python Software Foundation.
This page is licensed under the Python Software Foundation License Version 2. Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License. See History and License for more information. The Python Software Foundation is a non-profit corporation. Please donate. Last updated on Nov 12, 2026 (11:13 UTC). Found a bug? Created using Sphinx 9.1.1. |
| You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |