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