1.. highlightlang:: c 2 3.. _stable: 4 5*********************************** 6Stable Application Binary Interface 7*********************************** 8 9Traditionally, the C API of Python will change with every release. Most changes 10will be source-compatible, typically by only adding API, rather than changing 11existing API or removing API (although some interfaces do get removed after 12being deprecated first). 13 14Unfortunately, the API compatibility does not extend to binary compatibility 15(the ABI). The reason is primarily the evolution of struct definitions, where 16addition of a new field, or changing the type of a field, might not break the 17API, but can break the ABI. As a consequence, extension modules need to be 18recompiled for every Python release (although an exception is possible on Unix 19when none of the affected interfaces are used). In addition, on Windows, 20extension modules link with a specific pythonXY.dll and need to be recompiled to 21link with a newer one. 22 23Since Python 3.2, a subset of the API has been declared to guarantee a stable 24ABI. Extension modules wishing to use this API (called "limited API") need to 25define ``Py_LIMITED_API``. A number of interpreter details then become hidden 26from the extension module; in return, a module is built that works on any 3.x 27version (x>=2) without recompilation. 28 29In some cases, the stable ABI needs to be extended with new functions. 30Extension modules wishing to use these new APIs need to set ``Py_LIMITED_API`` 31to the ``PY_VERSION_HEX`` value (see :ref:`apiabiversion`) of the minimum Python 32version they want to support (e.g. ``0x03030000`` for Python 3.3). Such modules 33will work on all subsequent Python releases, but fail to load (because of 34missing symbols) on the older releases. 35 36As of Python 3.2, the set of functions available to the limited API is 37documented in :pep:`384`. In the C API documentation, API elements that are not 38part of the limited API are marked as "Not part of the limited API." 39