diff options
Diffstat (limited to 'Doc/c-api/stable.rst')
| -rw-r--r-- | Doc/c-api/stable.rst | 39 |
1 files changed, 39 insertions, 0 deletions
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst new file mode 100644 index 0000000..2688c1c --- /dev/null +++ b/Doc/c-api/stable.rst @@ -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? |