Close #15465: Document C API version macros

ncoghlan · ncoghlan · commit 7d82c8621bb7 · 2013-03-07T23:14:44.000+10:00
Mostly moving the existing macro docs over from the standard
library docs to the C API docs where they belong.

Patch by Kushal Das.
diff --git a/Doc/c-api/apiabiversion.rst 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
@@ -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
@@ -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
@@ -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
@@ -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
