From 7d82c8621bb72035b2e36388d616533dacfc2e43 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Thu, 7 Mar 2013 23:14:44 +1000 Subject: Close #15465: Document C API version macros Mostly moving the existing macro docs over from the standard library docs to the C API docs where they belong. Patch by Kushal Das. --- Doc/c-api/apiabiversion.rst | 39 +++++++++++++++++++++++++++++++++++++++ Doc/c-api/index.rst | 1 + Doc/c-api/stable.rst | 20 +++++++++++--------- Doc/library/sys.rst | 24 +----------------------- Misc/NEWS | 3 +++ 5 files changed, 55 insertions(+), 32 deletions(-) create mode 100644 Doc/c-api/apiabiversion.rst 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. diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 6264437..aad32d2 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -598,29 +598,7 @@ always available. :term:`struct sequence` :data:`sys.version_info` may be used for a more human-friendly encoding of the same information. - The ``hexversion`` is a 32-bit number with the following layout: - - +-------------------------+------------------------------------------------+ - | Bits (big endian order) | Meaning | - +=========================+================================================+ - | :const:`1-8` | ``PY_MAJOR_VERSION`` (the ``2`` in | - | | ``2.1.0a3``) | - +-------------------------+------------------------------------------------+ - | :const:`9-16` | ``PY_MINOR_VERSION`` (the ``1`` in | - | | ``2.1.0a3``) | - +-------------------------+------------------------------------------------+ - | :const:`17-24` | ``PY_MICRO_VERSION`` (the ``0`` in | - | | ``2.1.0a3``) | - +-------------------------+------------------------------------------------+ - | :const:`25-28` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, | - | | ``0xB`` for beta, ``0xC`` for release | - | | candidate and ``0xF`` for final) | - +-------------------------+------------------------------------------------+ - | :const:`29-32` | ``PY_RELEASE_SERIAL`` (the ``3`` in | - | | ``2.1.0a3``, zero for final releases) | - +-------------------------+------------------------------------------------+ - - Thus ``2.1.0a3`` is hexversion ``0x020100a3``. + More details of ``hexversion`` can be found at :ref:`apiabiversion` .. data:: implementation diff --git a/Misc/NEWS b/Misc/NEWS index 3665001..9b94b13 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -797,6 +797,9 @@ Tools/Demos Documentation ------------- +- Issue #15465: Document the versioning macros in the C API docs rather than + the standard library docs. Patch by Kushal Das. + - Issue #16406: Combine the pages for uploading and registering to PyPI. - Issue #16403: Document how distutils uses the maintainer field in -- cgit v0.12