bpo-43795: PEP 652 user documentation (GH-25668) (GH-26034)
- Reformat the C API and ABI Versioning page (and extend/clarify a bit)
- Rewrite the stable ABI docs into a general text on C API Compatibility
- Add a list of Limited API contents, and notes for the individual items.
- Replace `Include/README.rst` with a link to a devguide page with the same info
(cherry picked from commit b05955d6f5f149523b5855a335444b7c6324bdb7)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
diff --git a/Doc/c-api/apiabiversion.rst b/Doc/c-api/apiabiversion.rst
index b8a8f2f..04050f7 100644
--- a/Doc/c-api/apiabiversion.rst
+++ b/Doc/c-api/apiabiversion.rst
@@ -6,34 +6,57 @@
API and ABI Versioning
***********************
-``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
+CPython exposes its version number in the following macros.
+Note that these correspond to the version code is **built** with,
+not necessarily the version used at **run time**.
-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:
+See :ref:`stable` for a discussion of API and ABI stability across versions.
- +-------+-------------------------+------------------------------------------------+
- | 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) |
- +-------+-------------------------+------------------------------------------------+
+.. c:macro:: PY_MAJOR_VERSION
-Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
+ The ``3`` in ``3.4.1a2``.
+
+.. c:macro:: PY_MINOR_VERSION
+
+ The ``4`` in ``3.4.1a2``.
+
+.. c:macro:: PY_MICRO_VERSION
+
+ The ``1`` in ``3.4.1a2``.
+
+.. c:macro:: PY_RELEASE_LEVEL
+
+ The ``a`` in ``3.4.1a2``.
+ This can be ``0xA`` for alpha, ``0xB`` for beta, ``0xC`` for release
+ candidate or ``0xF`` for final.
+
+.. c:macro:: PY_RELEASE_SERIAL
+
+ The ``2`` in ``3.4.1a2``. Zero for final releases.
+
+.. c:macro:: PY_VERSION_HEX
+
+ The Python version number encoded in a single integer.
+
+ 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 | Value for ``3.4.1a2`` |
+ +=======+=========================+=========================+==========================+
+ | 1 | 1-8 | ``PY_MAJOR_VERSION`` | ``0x03`` |
+ +-------+-------------------------+-------------------------+--------------------------+
+ | 2 | 9-16 | ``PY_MINOR_VERSION`` | ``0x04`` |
+ +-------+-------------------------+-------------------------+--------------------------+
+ | 3 | 17-24 | ``PY_MICRO_VERSION`` | ``0x01`` |
+ +-------+-------------------------+-------------------------+--------------------------+
+ | 4 | 25-28 | ``PY_RELEASE_LEVEL`` | ``0xA`` |
+ + +-------------------------+-------------------------+--------------------------+
+ | | 29-32 | ``PY_RELEASE_SERIAL`` | ``0x2`` |
+ +-------+-------------------------+-------------------------+--------------------------+
+
+ Thus ``3.4.1a2`` is hexversion ``0x030401a2`` and ``3.10.0`` is
+ hexversion ``0x030a00f0``.
+
All the given macros are defined in :source:`Include/patchlevel.h`.
-