1.. highlight:: c 2 3.. _stable: 4 5*************** 6C API Stability 7*************** 8 9Unless documented otherwise, Python's C API is covered by the Backwards 10Compatibility Policy, :pep:`387`. 11Most changes to it are source-compatible (typically by only adding new API). 12Changing existing API or removing API is only done after a deprecation period 13or to fix serious issues. 14 15CPython's Application Binary Interface (ABI) is forward- and 16backwards-compatible across a minor release (if these are compiled the same 17way; see :ref:`stable-abi-platform` below). 18So, code compiled for Python 3.10.0 will work on 3.10.8 and vice versa, 19but will need to be compiled separately for 3.9.x and 3.11.x. 20 21There are two tiers of C API with different stability expectations: 22 23- :ref:`Unstable API <unstable-c-api>`, may change in minor versions without 24 a deprecation period. It is marked by the ``PyUnstable`` prefix in names. 25- :ref:`Limited API <limited-c-api>`, is compatible across several minor releases. 26 When :c:macro:`Py_LIMITED_API` is defined, only this subset is exposed 27 from ``Python.h``. 28 29These are discussed in more detail below. 30 31Names prefixed by an underscore, such as ``_Py_InternalState``, 32are private API that can change without notice even in patch releases. 33If you need to use this API, consider reaching out to 34`CPython developers <https://discuss.python.org/c/core-dev/c-api/30>`_ 35to discuss adding public API for your use case. 36 37.. _unstable-c-api: 38 39Unstable C API 40============== 41 42.. index:: single: PyUnstable 43 44Any API named with the ``PyUnstable`` prefix exposes CPython implementation 45details, and may change in every minor release (e.g. from 3.9 to 3.10) without 46any deprecation warnings. 47However, it will not change in a bugfix release (e.g. from 3.10.0 to 3.10.1). 48 49It is generally intended for specialized, low-level tools like debuggers. 50 51Projects that use this API are expected to follow 52CPython development and spend extra effort adjusting to changes. 53 54 55Stable Application Binary Interface 56=================================== 57 58For simplicity, this document talks about *extensions*, but the Limited API 59and Stable ABI work the same way for all uses of the API – for example, 60embedding Python. 61 62.. _limited-c-api: 63 64Limited C API 65------------- 66 67Python 3.2 introduced the *Limited API*, a subset of Python's C API. 68Extensions that only use the Limited API can be 69compiled once and be loaded on multiple versions of Python. 70Contents of the Limited API are :ref:`listed below <limited-api-list>`. 71 72.. c:macro:: Py_LIMITED_API 73 74 Define this macro before including ``Python.h`` to opt in to only use 75 the Limited API, and to select the Limited API version. 76 77 Define ``Py_LIMITED_API`` to the value of :c:macro:`PY_VERSION_HEX` 78 corresponding to the lowest Python version your extension supports. 79 The extension will be ABI-compatible with all Python 3 releases 80 from the specified one onward, and can use Limited API introduced up to that 81 version. 82 83 Rather than using the ``PY_VERSION_HEX`` macro directly, hardcode a minimum 84 minor version (e.g. ``0x030A0000`` for Python 3.10) for stability when 85 compiling with future Python versions. 86 87 You can also define ``Py_LIMITED_API`` to ``3``. This works the same as 88 ``0x03020000`` (Python 3.2, the version that introduced Limited API). 89 90 91.. _stable-abi: 92 93Stable ABI 94---------- 95 96To enable this, Python provides a *Stable ABI*: a set of symbols that will 97remain ABI-compatible across Python 3.x versions. 98 99.. note:: 100 101 The Stable ABI prevents ABI issues, like linker errors due to missing 102 symbols or data corruption due to changes in structure layouts or function 103 signatures. 104 However, other changes in Python can change the *behavior* of extensions. 105 See Python's Backwards Compatibility Policy (:pep:`387`) for details. 106 107The Stable ABI contains symbols exposed in the :ref:`Limited API 108<limited-c-api>`, but also other ones – for example, functions necessary to 109support older versions of the Limited API. 110 111On Windows, extensions that use the Stable ABI should be linked against 112``python3.dll`` rather than a version-specific library such as 113``python39.dll``. 114 115On some platforms, Python will look for and load shared library files named 116with the ``abi3`` tag (e.g. ``mymodule.abi3.so``). 117It does not check if such extensions conform to a Stable ABI. 118The user (or their packaging tools) need to ensure that, for example, 119extensions built with the 3.10+ Limited API are not installed for lower 120versions of Python. 121 122All functions in the Stable ABI are present as functions in Python's shared 123library, not solely as macros. This makes them usable from languages that don't 124use the C preprocessor. 125 126 127Limited API Scope and Performance 128--------------------------------- 129 130The goal for the Limited API is to allow everything that is possible with the 131full C API, but possibly with a performance penalty. 132 133For example, while :c:func:`PyList_GetItem` is available, its “unsafe” macro 134variant :c:func:`PyList_GET_ITEM` is not. 135The macro can be faster because it can rely on version-specific implementation 136details of the list object. 137 138Without ``Py_LIMITED_API`` defined, some C API functions are inlined or 139replaced by macros. 140Defining ``Py_LIMITED_API`` disables this inlining, allowing stability as 141Python's data structures are improved, but possibly reducing performance. 142 143By leaving out the ``Py_LIMITED_API`` definition, it is possible to compile 144a Limited API extension with a version-specific ABI. This can improve 145performance for that Python version, but will limit compatibility. 146Compiling with ``Py_LIMITED_API`` will then yield an extension that can be 147distributed where a version-specific one is not available – for example, 148for prereleases of an upcoming Python version. 149 150 151Limited API Caveats 152------------------- 153 154Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that 155code conforms to the :ref:`Limited API <limited-c-api>` or the :ref:`Stable ABI 156<stable-abi>`. ``Py_LIMITED_API`` only covers definitions, but an API also 157includes other issues, such as expected semantics. 158 159One issue that ``Py_LIMITED_API`` does not guard against is calling a function 160with arguments that are invalid in a lower Python version. 161For example, consider a function that starts accepting ``NULL`` for an 162argument. In Python 3.9, ``NULL`` now selects a default behavior, but in 163Python 3.8, the argument will be used directly, causing a ``NULL`` dereference 164and crash. A similar argument works for fields of structs. 165 166Another issue is that some struct fields are currently not hidden when 167``Py_LIMITED_API`` is defined, even though they're part of the Limited API. 168 169For these reasons, we recommend testing an extension with *all* minor Python 170versions it supports, and preferably to build with the *lowest* such version. 171 172We also recommend reviewing documentation of all used API to check 173if it is explicitly part of the Limited API. Even with ``Py_LIMITED_API`` 174defined, a few private declarations are exposed for technical reasons (or 175even unintentionally, as bugs). 176 177Also note that the Limited API is not necessarily stable: compiling with 178``Py_LIMITED_API`` with Python 3.8 means that the extension will 179run with Python 3.12, but it will not necessarily *compile* with Python 3.12. 180In particular, parts of the Limited API may be deprecated and removed, 181provided that the Stable ABI stays stable. 182 183 184.. _stable-abi-platform: 185 186Platform Considerations 187======================= 188 189ABI stability depends not only on Python, but also on the compiler used, 190lower-level libraries and compiler options. For the purposes of 191the :ref:`Stable ABI <stable-abi>`, these details define a “platform”. They 192usually depend on the OS type and processor architecture 193 194It is the responsibility of each particular distributor of Python 195to ensure that all Python versions on a particular platform are built 196in a way that does not break the Stable ABI. 197This is the case with Windows and macOS releases from ``python.org`` and many 198third-party distributors. 199 200 201.. _limited-api-list: 202 203Contents of Limited API 204======================= 205 206 207Currently, the :ref:`Limited API <limited-c-api>` includes the following items: 208 209.. limited-api-list:: 210