[Python-checkins] cpython (3.3): Close #15465: Document C API version macros
nick.coghlan
python-checkins at python.org
Thu Mar 7 14:45:15 CET 2013
http://hg.python.org/cpython/rev/adeafab9a18f
changeset: 82523:adeafab9a18f
branch: 3.3
parent: 82519:33208a574875
user: Nick Coghlan <ncoghlan at gmail.com>
date: Thu Mar 07 23:14:44 2013 +1000
summary:
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.
files:
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(-)
diff --git a/Doc/c-api/apiabiversion.rst b/Doc/c-api/apiabiversion.rst
new file mode 100644
--- /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
--- a/Doc/c-api/index.rst
+++ b/Doc/c-api/index.rst
@@ -23,3 +23,4 @@
memory.rst
objimpl.rst
stable.rst
+ apiabiversion.rst
diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
--- 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 @@
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
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -598,29 +598,7 @@
: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
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -797,6 +797,9 @@
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
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list