traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add Stable ABI documentation.

This commit is contained in:
Martin v. Löwis 2012-06-22 12:49:08 +02:00
parent 7800f75827
commit c06917bf12
2 changed files with 40 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Doc/c-api/index.rst
View File

@ -25,3 +25,4 @@ document the API functions in detail.
init.rst init.rst
memory.rst memory.rst
objimpl.rst objimpl.rst
stable.rst

39
Doc/c-api/stable.rst Normal file
View File

@ -0,0 +1,39 @@
.. 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?