diff options
Diffstat (limited to 'Doc/c-api')
| -rw-r--r-- | Doc/c-api/apiabiversion.rst | 39 | ||||
| -rw-r--r-- | Doc/c-api/index.rst | 1 | ||||
| -rw-r--r-- | Doc/c-api/stable.rst | 20 |
3 files changed, 51 insertions, 9 deletions
diff --git a/Doc/c-api/apiabiversion.rst b/Doc/c-api/apiabiversion.rst new file mode 100644 index 0000000..f6d52df --- /dev/null +++ b/Doc/c-api/apiabiversion.rst @@ -0,0 +1,39 @@ +.. highlightlang:: c + +.. _apiabiversion: + +*********************** +API and ABI Versioning +*********************** + +``PY_VERSION_HEX`` is the Python version number encoded in a single integer. + +For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying +version information can be found by treating it as a 32 bit number in +the following manner: + + +-------+-------------------------+------------------------------------------------+ + | Bytes | Bits (big endian order) | Meaning | + +=======+=========================+================================================+ + | ``1`` | ``1-8`` | ``PY_MAJOR_VERSION`` (the ``3`` in | + | | | ``3.4.1a2``) | + +-------+-------------------------+------------------------------------------------+ + | ``2`` | ``9-16`` | ``PY_MINOR_VERSION`` (the ``4`` in | + | | | ``3.4.1a2``) | + +-------+-------------------------+------------------------------------------------+ + | ``3`` | ``17-24`` | ``PY_MICRO_VERSION`` (the ``1`` in | + | | | ``3.4.1a2``) | + +-------+-------------------------+------------------------------------------------+ + | ``4`` | ``25-28`` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, | + | | | ``0xB`` for beta, ``0xC`` for release | + | | | candidate and ``0xF`` for final), in this | + | | | case it is alpha. | + | +-------------------------+------------------------------------------------+ + | | ``29-32`` | ``PY_RELEASE_SERIAL`` (the ``2`` in | + | | | ``3.4.1a2``, zero for final releases) | + +-------+-------------------------+------------------------------------------------+ + +Thus ``3.4.1a2`` is hexversion ``0x030401a2``. + +All the given macros are defined in :source:`Include/patchlevel.h`. + diff --git a/Doc/c-api/index.rst b/Doc/c-api/index.rst index 7b73e5b..591136e 100644 --- a/Doc/c-api/index.rst +++ b/Doc/c-api/index.rst @@ -23,3 +23,4 @@ document the API functions in detail. memory.rst objimpl.rst stable.rst + apiabiversion.rst diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index 2688c1c..a7c9ef9 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -2,9 +2,9 @@ .. _stable: -********************************** -Stable Appliction Binary Interface -********************************** +*********************************** +Stable Application Binary Interface +*********************************** Traditionally, the C API of Python will change with every release. Most changes will be source-compatible, typically by only adding API, @@ -23,13 +23,15 @@ 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 +``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 any 3.x version (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 set +``Py_LIMITED_API`` to the ``PY_VERSION_HEX`` value (see +:ref:`apiabiversion`) 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. |