Respond to reviews

python · encukou · Apr 16, 2026 · Mar 31, 2026 · Apr 2, 2026 · Apr 2, 2026
commit e7e102a99c65ef1dc1d2921afd2ab7c928c8a458
@@ -685,10 +685,11 @@ remove it.
    Usually, there is only one variable of this type for each extension module
    defined this way.
 
-   In the :ref:`Stable ABI <stable-abi>` for free-threaded builds (``abi3t``),
-   this struct is opaque, and unusable in practice.
-   The struct, including all members, is part of Stable ABI for
-   non-free-threaded builds (``abi3``).
+   The struct, including all members, is part of the
+   :ref:`Stable ABI <stable-abi>` for non-free-threaded builds (``abi3``).
+   In the Stable ABI for free-threaded builds (``abi3t``),
+   this struct is opaque, and unusable in practice; see :ref:`pymoduledef_slot`
+   for a replacement.
 
    .. c:member:: PyModuleDef_Base m_base
 
@@ -700,10 +701,10 @@ remove it.
 
          The type of :c:member:`!PyModuleDef.m_base`.
 
-         In the :ref:`Stable ABI <stable-abi>` for Free-Threaded Builds
-         (``abi3t``), this struct is opaque, and unusable in practice.
-         The struct is part of Stable ABI for
+         The struct is part of the :ref:`Stable ABI <stable-abi>` for
          non-free-threaded builds (``abi3``).
+         In the Stable ABI for Free-Threaded Builds
+         (``abi3t``), this struct is opaque, and unusable in practice.
 
       .. c:macro:: PyModuleDef_HEAD_INIT
 

@@ -125,10 +125,11 @@
 
 .. note::
 
-   When using a build tool (for example, Setuptools), the tool is
-   generally responsible for setting macros and synchronizing them with
-   extension filenames and other metadata.
-   Prefer using the tool's options over defining the macros manually.
+   Build tools (such as, for example, meson-python, scikit-build-core,
+   or Setuptools) often have a mechanism for setting macros and synchronizing
+   them with extension filenames and other metadata.
+   Prefer using such a mechanism, if it exists, over defining the
+   macros manually.
 
    The rest of this section is mainly relevant for tool authors, and for
    people who compile extensions manually.
@@ -150,10 +151,12 @@
 
 .. version-hex-cheatsheet::
 
-When the macro(s) are defined, ``Python.h`` will only expose API that is
+When one of the macros is defined, ``Python.h`` will only expose API that is
 compatible with the given Stable ABI -- that is, the
 :ref:`Limited API <limited-api-list>` plus some definitions that need to be
 visible to the compiler but should not be used directly.
+When both are defined, ``Python.h`` will only expose API compatible with
+both Stable ABIs.
 
 .. c:macro:: Py_LIMITED_API
 
@@ -169,7 +172,7 @@

   .. versionadded:: next

 Both macros specify a target ABI; the different naming style is due to
 backwards compatibility.

 .. admonition:: Historical note
@@ -186,7 +189,10 @@
 This means that there are two ways to build for both ``abi3`` and ``abi3t``:
 
 - define both :c:macro:`!Py_LIMITED_API` and :c:macro:`!Py_TARGET_ABI3T`, or
-- define only :c:macro:`!Py_LIMITED_API` and build for free-threaded Python.
+- define only :c:macro:`!Py_LIMITED_API` and:
+
+  - on Windows, define :c:macro:`!Py_GIL_DISABLED`;
+  - on other systems, use the headers of free-threaded build of Python.
 
 
 .. _limited-api-scope-and-performance:

@@ -380,6 +380,7 @@ class VersionHexCheatsheet(SphinxDirective):
     It should auto-update with the version being documented, so it must be an
     extension.
     """
+
     has_content = False
     required_arguments = 0
     optional_arguments = 0

@@ -409,8 +409,8 @@ the existing Stable ABI (``abi3``) and the version-specific ABI for
 free-threading (``cp315t``) separately.
 
 Stable ABI for Free-Threaded Builds should typically
-be selected in a build tool (such as Setuptools, meson-python, Cython,
-scikit-build-core, Maturin).
+be selected in a build tool (such as, for example, Setuptools, meson-python,
+scikit-build-core, or Maturin).
 At the time of writing, these tools did **not** support ``abi3t``.
 If this is the case for your tool, compile for ``cp315t`` separately.
 If not using a build tool -- or when writing such a tool -- you can select