mirror of
https://github.com/python/cpython.git
synced 2025-10-31 18:28:49 +00:00
7d82c8621b
Mostly moving the existing macro docs over from the standard library docs to the C API docs where they belong. Patch by Kushal Das.
41 lines
1.8 KiB
ReStructuredText
41 lines
1.8 KiB
ReStructuredText
.. highlightlang:: 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 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.
|
|
|
|
.. XXX copy exact list here? Into each functions definition?
|