mirror of https://github.com/python/cpython.git
39 lines
1.9 KiB
ReStructuredText
39 lines
1.9 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
.. _stable:
|
|
|
|
***********************************
|
|
Stable Application Binary Interface
|
|
***********************************
|
|
|
|
Traditionally, the C API of Python will change with every release. Most changes
|
|
will be source-compatible, typically by only adding API, rather than changing
|
|
existing API or removing API (although some interfaces do get removed after
|
|
being deprecated first).
|
|
|
|
Unfortunately, the API compatibility does not extend to binary compatibility
|
|
(the ABI). The reason is primarily the evolution of struct definitions, where
|
|
addition of a new field, or changing the type of a field, might not break the
|
|
API, but can break the ABI. As a consequence, extension modules need to be
|
|
recompiled for every Python release (although an exception is possible on Unix
|
|
when none of the affected interfaces are used). In addition, on Windows,
|
|
extension modules link with a specific pythonXY.dll and need to be recompiled to
|
|
link with a newer one.
|
|
|
|
Since Python 3.2, a subset of the API has been declared to guarantee a stable
|
|
ABI. Extension modules wishing to use this API (called "limited API") need to
|
|
define ``Py_LIMITED_API``. A number of interpreter details then become hidden
|
|
from the extension module; in return, a module is built that works on any 3.x
|
|
version (x>=2) without recompilation.
|
|
|
|
In some cases, the stable ABI needs to be extended with new functions.
|
|
Extension modules wishing to use these new APIs need to set ``Py_LIMITED_API``
|
|
to the ``PY_VERSION_HEX`` value (see :ref:`apiabiversion`) of the minimum Python
|
|
version they want to support (e.g. ``0x03030000`` for Python 3.3). Such modules
|
|
will work on all subsequent Python releases, but fail to load (because of
|
|
missing symbols) on the older releases.
|
|
|
|
As of Python 3.2, the set of functions available to the limited API is
|
|
documented in :pep:`384`. In the C API documentation, API elements that are not
|
|
part of the limited API are marked as "Not part of the limited API."
|