[3.12] gh-102304: doc: Add links to Stable ABI and Limited C API (#105345) (#105371)

* gh-102304: doc: Add links to Stable ABI and Limited C API (#105345)

* Add "limited-c-api" and "stable-api" references.
* Rename "stable-abi-list" reference to "limited-api-list".
* Makefile: Document files regenerated by "make regen-limited-abi"
* Remove first empty line in generated files:

  - Lib/test/test_stable_abi_ctypes.py
  - PC/python3dll.c

(cherry picked from commit bae415ad02c79cf3a2eec4aa6969221a12e6716f)

* gh-102304: Fix up Simple ABI doc (GH-105351)

(cherry picked from commit 0202aa002e06acef9aa55ace0d939103df19cadd)

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 1694aa2db9c9da4e1b9e1f411e8388c5725ee94f..a24ecac861e76bb488b81e4aefa9a1b732a8225e 100644 (file)
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -887,7 +887,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)
 
@@ -895,7 +895,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 3721fc0697f5cd830965ebfda2ace0b318f3922f..149d4d6bac3ee49cbddb1f5f35813575006f37e2 100644 (file)
--- a/Doc/c-api/stable.rst
+++ b/Doc/c-api/stable.rst
@@ -20,9 +20,9 @@ but will need to be compiled separately for 3.9.x and 3.10.x.
 
 There are two tiers of C API with different stability exepectations:
 
-- *Unstable API*, may change in minor versions without a deprecation period.
-  It is marked by the ``PyUnstable`` prefix in names.
-- *Limited API*, is compatible across several minor releases.
+- :ref:`Unstable API <unstable-c-api>`, may change in minor versions without
+  a deprecation period. It is marked by the ``PyUnstable`` prefix in names.
+- :ref:`Limited API <limited-c-api>`, is compatible across several minor releases.
   When :c:macro:`Py_LIMITED_API` is defined, only this subset is exposed
   from ``Python.h``.
 
@@ -55,19 +55,19 @@ CPython development and spend extra effort adjusting to changes.
 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
 
@@ -87,6 +87,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``.
@@ -131,9 +144,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.
@@ -166,9 +179,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
@@ -177,12 +190,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 7ce3578f2507929bd3d8ea8e08b1a89ca0e62bdf..766f881463c00fa997ecdc71192ab481b9e45372 100644 (file)
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -288,7 +288,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>`.
 
 
 .. data:: METH_FASTCALL | METH_KEYWORDS

diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst
index 89cd74335fd770f1043209bada7be4206cc591d2..bf261b9814456ea9a001b3e27efbf330a8bcc578 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
 
@@ -472,7 +472,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 *pfunc
 

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 0584989233de3fdfcb4ad09baeaec353a017d819..c6e783acdf0654668e04e8beb7393c1b2345ae77 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -2150,7 +2150,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 6771f378bfbc319be6243b44a62b0eddce0e73b3..33437b6193919ad5b7661c660eb654765b2041f8 100644 (file)
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -992,7 +992,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 0262054ae2b4a075898c81abcaf45b82aa862992..8adb85f3a874018d499cc748f21742e6b0bda95c 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/library/test.rst b/Doc/library/test.rst
index 20f633b8f569be35434d5606d6872cabc88c3816..1b045c7de83a804ea01e0428142c25ee398a4ee2 100644 (file)
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -803,7 +803,7 @@ The :mod:`test.support` module defines the following functions:
 
 .. decorator:: requires_limited_api
 
-   Decorator for only running the test if :ref:`Limited C API <stable>`
+   Decorator for only running the test if :ref:`Limited C API <limited-c-api>`
    is available.
 
 

diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 48606f3be42e3cc43452702283234a3624acbda4..c06ce78368985770f4592fbfb20f196885e14dae 100644 (file)
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -2650,7 +2650,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/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 18c4ae049ab7f84fc69f93d8c51a6cda04c6bd3a..287549fe30ec1abfd874cec27639fb917fd65b8b 100644 (file)
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -1580,7 +1580,7 @@ New Features
 
   (Contributed by Petr Viktorin in :gh:`103509`.)
 
-* Added the new limited C API function :c:func:`PyType_FromMetaclass`,
+* Added the new :ref:`limited C API <limited-c-api>` function :c:func:`PyType_FromMetaclass`,
   which generalizes the existing :c:func:`PyType_FromModuleAndSpec` using
   an additional metaclass argument.
   (Contributed by Wenzel Jakob in :gh:`93012`.)

diff --git a/Lib/test/test_stable_abi_ctypes.py b/Lib/test/test_stable_abi_ctypes.py
index 60ad3603ae92233c145cb98d01502c95f0a5255c..689836754883894027635fc8056b4c538a86c5c2 100644 (file)
--- a/Lib/test/test_stable_abi_ctypes.py
+++ b/Lib/test/test_stable_abi_ctypes.py
@@ -1,5 +1,4 @@
-
-# Generated by Tools/scripts/stable_abi.py
+# Generated by Tools/build/stable_abi.py
 
 """Test that all symbols of the Stable ABI are accessible using ctypes
 """

diff --git a/Misc/NEWS.d/3.11.0a1.rst b/Misc/NEWS.d/3.11.0a1.rst
index 7670e482ede5b613f0e2b440687e4962027d060e..447d5c0e7d9032d9e0bdcf9959de76281461df2d 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 225bd61e90d4a82e7d95566780974f9d81858a2e..cf26137dff19ef4771977c7c878834da0e10c0d7 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.
 

diff --git a/Modules/_testcapi_feature_macros.inc b/Modules/_testcapi_feature_macros.inc
index b1763b57d913c2e7e58ee7fa773711314259985d..a076e7149800743a48a4c502b0d103df8d695838 100644 (file)
--- a/Modules/_testcapi_feature_macros.inc
+++ b/Modules/_testcapi_feature_macros.inc
@@ -1,4 +1,4 @@
-// Generated by Tools/scripts/stable_abi.py
+// Generated by Tools/build/stable_abi.py
 
 // Add an entry in dict `result` for each Stable ABI feature macro.
 

diff --git a/PC/python3dll.c b/PC/python3dll.c
index f2c0d9dee883d9936d82d1ee073fc794bdf4d8d8..5665d5530e2360cdf33e54b33fe0f80bd01c5c8b 100755 (executable)
--- a/PC/python3dll.c
+++ b/PC/python3dll.c
@@ -1,4 +1,3 @@
-
 /* Re-export stable Python ABI */
 
 /* Generated by Tools/build/stable_abi.py */

diff --git a/Tools/build/stable_abi.py b/Tools/build/stable_abi.py
index 42b2dd92307bbf09fab7df4777f01072a234c3f0..4cd1cd953d0d2995013fac278bd6e9be58abdfde 100644 (file)
--- a/Tools/build/stable_abi.py
+++ b/Tools/build/stable_abi.py
@@ -183,7 +183,7 @@ def generator(var_name, default_path):
 def gen_python3dll(manifest, args, outfile):
     """Generate/check the source for the Windows stable ABI library"""
     write = partial(print, file=outfile)
-    content = f"""
+    content = f"""\
         /* Re-export stable Python ABI */
 
         /* Generated by {SCRIPT_NAME} */
@@ -267,8 +267,8 @@ def gen_doc_annotations(manifest, args, outfile):
 def gen_ctypes_test(manifest, args, outfile):
     """Generate/check the ctypes-based test for exported symbols"""
     write = partial(print, file=outfile)
-    write(textwrap.dedent('''
-        # Generated by Tools/scripts/stable_abi.py
+    write(textwrap.dedent(f'''\
+        # Generated by {SCRIPT_NAME}
 
         """Test that all symbols of the Stable ABI are accessible using ctypes
         """
@@ -341,7 +341,7 @@ def gen_ctypes_test(manifest, args, outfile):
 def gen_testcapi_feature_macros(manifest, args, outfile):
     """Generate/check the stable ABI list for documentation annotations"""
     write = partial(print, file=outfile)
-    write('// Generated by Tools/scripts/stable_abi.py')
+    write(f'// Generated by {SCRIPT_NAME}')
     write()
     write('// Add an entry in dict `result` for each Stable ABI feature macro.')
     write()