[3.11] gh-102304: Add links to the Stable ABI and Limited C API docs (#105345) (...

* Add "limited-c-api" and "stable-api" targets
* Rename the "stable-abi-list" target to "limited-api-list"

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 82050845237bbdf37321add7d27381e6a9c591eb..320f1e6dbcc4ea88bfed064ef38c436bf6b8f944 100644 (file)
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -806,7 +806,7 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
    depth limit.
 
    .. versionchanged:: 3.9
-      This function is now also available in the limited API.
+      This function is now also available in the :ref:`limited API <limited-c-api>`.
 
 .. c:function:: void Py_LeaveRecursiveCall(void)
 
@@ -814,7 +814,7 @@ because the :ref:`call protocol <call>` takes care of recursion handling.
    *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
 
    .. versionchanged:: 3.9
-      This function is now also available in the limited API.
+      This function is now also available in the :ref:`limited API <limited-c-api>`.
 
 Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
 special recursion handling.  In addition to protecting the stack,

diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst
index a697f6cd3edd900faf9c6b297a4c1dfda3465d72..4817da41e3e2174fa67f994cf95b495914b2dc78 100644 (file)
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -25,19 +25,19 @@ are private API that can change without notice even in patch releases.
 Stable Application Binary Interface
 ===================================
 
+For simplicity, this document talks about *extensions*, but the Limited API
+and Stable ABI work the same way for all uses of the API – for example,
+embedding Python.
+
+.. _limited-c-api:
+
+Limited C API
+-------------
+
 Python 3.2 introduced the *Limited API*, a subset of Python's C API.
 Extensions that only use the Limited API can be
 compiled once and work with multiple versions of Python.
-Contents of the Limited API are :ref:`listed below <stable-abi-list>`.
-
-To enable this, Python provides a *Stable ABI*: a set of symbols that will
-remain compatible across Python 3.x versions. The Stable ABI contains symbols
-exposed in the Limited API, but also other ones – for example, functions
-necessary to support older versions of the Limited API.
-
-(For simplicity, this document talks about *extensions*, but the Limited API
-and Stable ABI work the same way for all uses of the API – for example,
-embedding Python.)
+Contents of the Limited API are :ref:`listed below <limited-api-list>`.
 
 .. c:macro:: Py_LIMITED_API
 
@@ -57,6 +57,19 @@ embedding Python.)
    You can also define ``Py_LIMITED_API`` to ``3``. This works the same as
    ``0x03020000`` (Python 3.2, the version that introduced Limited API).
 
+
+.. _stable-abi:
+
+Stable ABI
+----------
+
+To enable this, Python provides a *Stable ABI*: a set of symbols that will
+remain compatible across Python 3.x versions.
+
+The Stable ABI contains symbols exposed in the :ref:`Limited API
+<limited-c-api>`, but also other ones – for example, functions necessary to
+support older versions of the Limited API.
+
 On Windows, extensions that use the Stable ABI should be linked against
 ``python3.dll`` rather than a version-specific library such as
 ``python39.dll``.
@@ -101,9 +114,9 @@ Limited API Caveats
 -------------------
 
 Note that compiling with ``Py_LIMITED_API`` is *not* a complete guarantee that
-code conforms to the Limited API or the Stable ABI. ``Py_LIMITED_API`` only
-covers definitions, but an API also includes other issues, such as expected
-semantics.
+code conforms to the :ref:`Limited API <limited-c-api>` or the :ref:`Stable ABI
+<stable-abi>`. ``Py_LIMITED_API`` only covers definitions, but an API also
+includes other issues, such as expected semantics.
 
 One issue that ``Py_LIMITED_API`` does not guard against is calling a function
 with arguments that are invalid in a lower Python version.
@@ -136,9 +149,9 @@ Platform Considerations
 =======================
 
 ABI stability depends not only on Python, but also on the compiler used,
-lower-level libraries and compiler options. For the purposes of the Stable ABI,
-these details define a “platform”. They usually depend on the OS
-type and processor architecture
+lower-level libraries and compiler options. For the purposes of
+the :ref:`Stable ABI <stable-abi>`, these details define a “platform”. They
+usually depend on the OS type and processor architecture
 
 It is the responsibility of each particular distributor of Python
 to ensure that all Python versions on a particular platform are built
@@ -147,12 +160,12 @@ This is the case with Windows and macOS releases from ``python.org`` and many
 third-party distributors.
 
 
-.. _stable-abi-list:
+.. _limited-api-list:
 
 Contents of Limited API
 =======================
 
 
-Currently, the Limited API includes the following items:
+Currently, the :ref:`Limited API <limited-c-api>` includes the following items:
 
 .. limited-api-list::

diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index c2903b9ec3285bfa113213c08a4a33d69f6cde22..304cc31575b1dc870f402dae46c6c1b5c600ba1e 100644 (file)
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -318,7 +318,7 @@ There are these calling conventions:
 
    .. versionchanged:: 3.10
 
-      ``METH_FASTCALL`` is now part of the stable ABI.
+      ``METH_FASTCALL`` is now part of the :ref:`stable ABI <stable-abi>`.
 
 
 .. _METH_FASTCALL-METH_KEYWORDS:

diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 01d7fc4dc1ecf1860cc07ab4ecbec51d3fe6b2da..a7ca19677134d09195a098e501e498403fa24818 100644 (file)
--- a/Doc/c-api/type.rst
+++ b/Doc/c-api/type.rst
@@ -42,7 +42,7 @@ Type Objects
    Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
    meant for use with ``Py_LIMITED_API``; the individual flag bits are
    guaranteed to be stable across Python releases, but access to
-   :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
+   :c:member:`~PyTypeObject.tp_flags` itself is not part of the :ref:`limited API <limited-c-api>`.
 
    .. versionadded:: 3.2
 
@@ -301,7 +301,7 @@ The following functions and structs are used to create
      .. versionchanged:: 3.11
         :c:member:`~PyBufferProcs.bf_getbuffer` and
         :c:member:`~PyBufferProcs.bf_releasebuffer` are now available
-        under the limited API.
+        under the :ref:`limited API <limited-c-api>`.
 
    .. c:member:: void *PyType_Slot.pfunc
 

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 62711802a783ae4e9e7abe28b1d6d9df243bb531..8b662ceac84e7bd73f17c59ba1afc3a50fb50577 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -2082,7 +2082,7 @@ This results in types that are limited relative to types defined in Python:
   include any subinterpreter-specific state.
 
 Also, since :c:type:`PyTypeObject` is only part of the :ref:`Limited API
-<stable>` as an opaque struct, any extension modules using static types must be
+<limited-c-api>` as an opaque struct, any extension modules using static types must be
 compiled for a specific Python minor version.
 
 

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 146511b9e3658a46f61842a44f38f8dd09e882fe..686252d808653d12b8f8fc31b29aa02447393d98 100644 (file)
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -1084,7 +1084,7 @@ These are the UTF-8 codec APIs:
       The return type is now ``const char *`` rather of ``char *``.
 
    .. versionchanged:: 3.10
-      This function is a part of the :ref:`limited API <stable>`.
+      This function is a part of the :ref:`limited API <limited-c-api>`.
 
 
 .. c:function:: const char* PyUnicode_AsUTF8(PyObject *unicode)

diff --git a/Doc/howto/isolating-extensions.rst b/Doc/howto/isolating-extensions.rst
index 0362fa6c68544358ee4aa6874b967816da11582a..732fd6f993b722f891fb3323492f2da7f875574e 100644 (file)
--- a/Doc/howto/isolating-extensions.rst
+++ b/Doc/howto/isolating-extensions.rst
@@ -461,7 +461,7 @@ Module State Access from Slot Methods, Getters and Setters
 
    .. After adding to limited API:
 
-      If you use the :ref:`limited API <stable>,
+      If you use the :ref:`limited API <limited-c-api>`,
       you must update ``Py_LIMITED_API`` to ``0x030b0000``, losing ABI
       compatibility with earlier versions.
 

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index c93541d18582de27100b98f500c93a10a3ea516f..fda4fbcb122dcf9435fe902ff8eb19c04cdb44ca 100644 (file)
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -2654,7 +2654,7 @@ Removed
   * :c:func:`PyMarshal_WriteObjectToString`
   * the ``Py_MARSHAL_VERSION`` macro
 
-  These are not part of the :ref:`limited API <stable-abi-list>`.
+  These are not part of the :ref:`limited API <limited-api-list>`.
 
   (Contributed by Victor Stinner in :issue:`45474`.)
 

diff --git a/Misc/NEWS.d/3.11.0a1.rst b/Misc/NEWS.d/3.11.0a1.rst
index fe21d9b5e6609363a4712d071cb53cff3c1a9c78..46c65300abf2c26796cc4a5a7df65be32115a0a8 100644 (file)
--- a/Misc/NEWS.d/3.11.0a1.rst
+++ b/Misc/NEWS.d/3.11.0a1.rst
@@ -4980,7 +4980,7 @@ Removed documentation for the removed ``PyParser_*`` C API.
 .. nonce: fy0AXK
 .. section: C API
 
-The list in :ref:`stable-abi-list` now shows the public name
+The list in :ref:`limited-api-list` now shows the public name
 :c:struct:`PyFrameObject` rather than ``_frame``. The non-existing entry
 ``_node`` no longer appears in the list.
 

diff --git a/Misc/NEWS.d/3.11.0a2.rst b/Misc/NEWS.d/3.11.0a2.rst
index d4ae7dc30b04b1786896b7b2d1d014e9797822b6..3f9a66298faa1b73aebc4c380d4f9b8645b529fd 100644 (file)
--- a/Misc/NEWS.d/3.11.0a2.rst
+++ b/Misc/NEWS.d/3.11.0a2.rst
@@ -1234,7 +1234,7 @@ defined:
 * :c:func:`PyMarshal_WriteObjectToString`
 * the ``Py_MARSHAL_VERSION`` macro
 
-These are not part of the :ref:`limited API <stable-abi-list>`.
+These are not part of the :ref:`limited API <limited-api-list>`.
 
 Patch by Victor Stinner.