Lines Matching +full:api +full:- +full:version
6 C API Stability
9 Unless documented otherwise, Python's C API is covered by the Backwards
11 Most changes to it are source-compatible (typically by only adding new API).
12 Changing existing API or removing API is only done after a deprecation period
15 CPython's Application Binary Interface (ABI) is forward- and
16 backwards-compatible across a minor release (if these are compiled the same
17 way; see :ref:`stable-abi-platform` below).
21 There are two tiers of C API with different stability expectations:
23 - :ref:`Unstable API <unstable-c-api>`, may change in minor versions without
25 - :ref:`Limited API <limited-c-api>`, is compatible across several minor releases.
32 are private API that can change without notice even in patch releases.
33 If you need to use this API, consider reaching out to
34 `CPython developers <https://discuss.python.org/c/core-dev/c-api/30>`_
35 to discuss adding public API for your use case.
37 .. _unstable-c-api:
39 Unstable C API
44 Any API named with the ``PyUnstable`` prefix exposes CPython implementation
49 It is generally intended for specialized, low-level tools like debuggers.
51 Projects that use this API are expected to follow
58 For simplicity, this document talks about *extensions*, but the Limited API
59 and Stable ABI work the same way for all uses of the API – for example,
62 .. _limited-c-api:
64 Limited C API
65 -------------
67 Python 3.2 introduced the *Limited API*, a subset of Python's C API.
68 Extensions that only use the Limited API can be
70 Contents of the Limited API are :ref:`listed below <limited-api-list>`.
75 the Limited API, and to select the Limited API version.
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.
84 minor version (e.g. ``0x030A0000`` for Python 3.10) for stability when
88 ``0x03020000`` (Python 3.2, the version that introduced Limited API).
91 .. _stable-abi:
94 ----------
97 remain ABI-compatible across Python 3.x versions.
107 The Stable ABI contains symbols exposed in the :ref:`Limited API
108 <limited-c-api>`, but also other ones – for example, functions necessary to
109 support older versions of the Limited API.
112 ``python3.dll`` rather than a version-specific library such as
119 extensions built with the 3.10+ Limited API are not installed for lower
127 Limited API Scope and Performance
128 ---------------------------------
130 The goal for the Limited API is to allow everything that is possible with the
131 full C API, but possibly with a performance penalty.
135 The macro can be faster because it can rely on version-specific implementation
138 Without ``Py_LIMITED_API`` defined, some C API functions are inlined or
144 a Limited API extension with a version-specific ABI. This can improve
145 performance for that Python version, but will limit compatibility.
147 distributed where a version-specific one is not available – for example,
148 for prereleases of an upcoming Python version.
151 Limited API Caveats
152 -------------------
155 code 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
160 with arguments that are invalid in a lower Python version.
167 ``Py_LIMITED_API`` is defined, even though they're part of the Limited API.
170 versions it supports, and preferably to build with the *lowest* such version.
172 We also recommend reviewing documentation of all used API to check
173 if it is explicitly part of the Limited API. Even with ``Py_LIMITED_API``
177 Also note that the Limited API is not necessarily stable: compiling with
180 In particular, parts of the Limited API may be deprecated and removed,
184 .. _stable-abi-platform:
190 lower-level libraries and compiler options. For the purposes of
191 the :ref:`Stable ABI <stable-abi>`, these details define a “platform”. They
198 third-party distributors.
201 .. _limited-api-list:
203 Contents of Limited API
207 Currently, the :ref:`Limited API <limited-c-api>` includes the following items:
209 .. limited-api-list::