traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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.
This commit is contained in:
Nick Coghlan 2013-03-07 23:14:44 +10:00
parent 4f1974496a
commit 7d82c8621b
5 changed files with 55 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Doc/c-api/apiabiversion.rst Normal file
View File

@ -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`.

1
Doc/c-api/index.rst
View File

@ -23,3 +23,4 @@ document the API functions in detail.
memory.rst
objimpl.rst
stable.rst
apiabiversion.rst

20
Doc/c-api/stable.rst
View File

@ -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.

24
Doc/library/sys.rst
View File

@ -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

3
Misc/NEWS
View File

@ -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