Apply suggestions from code review

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: encukou

peps/pep-0803.rst

@@ -5,17 +5,17 @@ Discussions-To: Pending
 Status: Draft
 Type: Standards Track
 Requires: 703, 793, 697
-Created: 08-Aug-2025
+Created: 19-Aug-2025
 Python-Version: 3.15
 
 
 Abstract
 ========
 
-Stable ABI 3.15 will be compatible with both free-threaded and GIL-enabled
-builds.
-To allow this, the ``PyObject`` internal structure and related APIs
-will be removed from the Limited API, requiring migration to new API
+Version 3.15 of the Stable ABI will be compatible with both free-threaded and
+GIL-enabled builds.
+To allow this, the :c:type:`PyObject` internal structure and related APIs
+will be removed from version 3.15 of the Limited API, requiring migration to new API
 for common tasks like defining modules and most classes.
 
 
@@ -29,6 +29,11 @@ that is, an interpreter or extension built without ``Py_GIL_DISABLED``.
 Motivation
 ==========
 
+The Stable ABI is currently not available for free-threaded builds.
+Extensions will fail to build when :c:macro:`Py_LIMITED_API` is defined,
+and extensions built for GIL-enabled builds of CPython will fail to load (or crash)
+on free-threaded builds.
+
 In its `acceptance post <https://discuss.python.org/t/84319/123>`__
 for :pep:`779`, the Steering Council stated that it “expects that Stable ABI
 for free-threading should be prepared and defined for Python 3.15”.
@@ -42,9 +47,10 @@ Background
 Python's Stable ABI, as defined in :pep:`384` and :pep:`652`, provides a way to
 compile extension modules that can be loaded on multiple versions of the
 CPython interpreter.
-Several projects use this to limit the number of *wheels* (binary artefacts)
+Several projects use this to limit the number of
+:ref:`wheels <packaging:binary-distribution-format>` (binary artefacts)
 that need to be built and distributed for each release, and/or to make it
-possible to test with pre-release versions of Python.
+easier to test with pre-release versions of Python.
 
 With free-threading builds (:pep:`703`) being on track to eventually become
 the default (:pep:`779`), we need a way to make the Stable ABI available
@@ -124,7 +130,7 @@ Implications
 Making the ``PyObject``, ``PyVarObject`` and ``PyModuleDef`` structures
 opaque means:
 
-- Their fields may not be accessed.
+- Their fields may not be directly accessed.
 
   For example, instead of ``o->ob_type``, extensions must use
   ``Py_TYPE(o)``.
@@ -147,15 +153,16 @@ opaque means:
 
 The following functions will become unusable in practice (in the new Limited
 API), since an extension cannot create valid, statically allocated, input
-for them. To ease the transition for extension developers, they will not yet be removed from the Limited API:
+for them. To ease the transition for extension developers,
+they will not yet be removed from the Limited API:
 
 - :c:func:`PyModuleDef_Init`
 - :c:func:`PyModule_Create`, :c:func:`PyModule_Create2`
 - :c:func:`PyModule_FromDefAndSpec`, :c:func:`PyModule_FromDefAndSpec2`
 
 
-New Export Hook (PEP 793)
--------------------------
+New Export Hook (:pep:`793`)
+----------------------------
 
 Implementation of this PEP requires :pep:`793` (``PyModExport``:
 A new entry  point for C extension modules) to be
@@ -182,7 +189,7 @@ The specifics are left to the C API working group
 
 This slot will become *mandatory* with the new export hook added in
 :pep:`793`.
-(The PEP currently says “there are no required slots”; it will be updated.)
+(That PEP currently says “there are no required slots”; it will be updated.)
 
 
 Check for older ``abi3``
@@ -257,10 +264,13 @@ This PEP combines several pieces, implemented individually:
 
 - Opaque ``PyObject`` is available in CPython main branch after defining the
   ``_Py_OPAQUE_PYOBJECT`` macro.
-  Implemented in GitHub pull request `#136505 <https://github.com/python/cpython/pull/136505>`__.
+  Implemented in GitHub pull request `python/cpython#136505
+  <https://github.com/python/cpython/pull/136505>`__.
 - For ``PyModExport``, see :pep:`793`.
-- For a version-checking slot, see GitHub pull request `#137212 <https://github.com/python/cpython/pull/137212>`__.
-- For a check for older ``abi3``, see GitHub pull request `#137957 <https://github.com/python/cpython/pull/137957>`__.
+- For a version-checking slot, see GitHub pull request `python/cpython#137212
+  <https://github.com/python/cpython/pull/137212>`__.
+- For a check for older ``abi3``, see GitHub pull request `python/cpython#137957
+  <https://github.com/python/cpython/pull/137957>`__.
 - For wheel tags, there is no implementation yet.
 - A porting guide is not yet written.