mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 08:34:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Close #15465: Document C API version macros

Browse source 
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
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.