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