mirror of https://github.com/python/cpython
40 lines
1.8 KiB
ReStructuredText
40 lines
1.8 KiB
ReStructuredText
|
.. highlightlang:: c
|
||
|
|
|
||
|
|
.. _stable:
|
||
|
|
|
||
|
|
**********************************
|
||
|
|
Stable Appliction 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. Extensions modules
|
||
|
|
wishing to use these new APIs need to set Py_LIMITED_API to the
|
||
|
|
PY_VERSION_HEX value 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?
|