Stable Application Binary Interface¶

Traditionally, the C API of Python will change with every release. Most changeswill be source-compatible, typically by only adding API, rather than changingexisting API or removing API (although some interfaces do get removed afterbeing deprecated first).

Unfortunately, the API compatibility does not extend to binary compatibility(the ABI). The reason is primarily the evolution of struct definitions, whereaddition of a new field, or changing the type of a field, might not break theAPI, but can break the ABI. As a consequence, extension modules need to berecompiled for every Python release (although an exception is possible on Unixwhen none of the affected interfaces are used). In addition, on Windows,extension modules link with a specific pythonXY.dll and need to be recompiled tolink with a newer one.

Since Python 3.2, a subset of the API has been declared to guarantee a stableABI. Extension modules wishing to use this API (called “limited API”) need todefinePy_LIMITED_API. A number of interpreter details then become hiddenfrom the extension module; in return, a module is built that works on any 3.xversion (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 setPy_LIMITED_APIto thePY_VERSION_HEX value (seeAPI and ABI Versioning) of the minimum Pythonversion they want to support (e.g.0x03030000 for Python 3.3). Such moduleswill work on all subsequent Python releases, but fail to load (because ofmissing symbols) on the older releases.

As of Python 3.2, the set of functions available to the limited API isdocumented inPEP 384. In the C API documentation, API elements that are notpart of the limited API are marked as “Not part of the limited API.”