Apply suggestions from code review

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Hood Chatham <roberthoodchatham@gmail.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: 4 people

peps/pep-0793.rst

@@ -1,12 +1,12 @@
 PEP: 793
 Title: PyModExport: A new entry point for C extension modules
 Author: Petr Viktorin <encukou@gmail.com>
-Discussions-To: https://discuss.python.org/t/84498
+Discussions-To: Pending
 Status: Draft
 Type: Standards Track
 Created: 23-May-2025
 Python-Version: 3.15
-Post-History: 23-May-2025
+Post-History: `14-Mar-2025 <https://discuss.python.org/t/84498/>`__,
 
 
 Abstract
@@ -23,7 +23,7 @@ To make this viable, we also specify new module slot types to replace
 ``PyModuleDef``'s fields, and to allow adding a *token* similar to the
 ``Py_tp_token`` used for type objects.
 
-We also add API for defining modules from slots dynamically.
+We also add an API for defining modules from slots dynamically.
 
 
 Background & Motivation
@@ -36,7 +36,7 @@ the current ``PyObject`` memory layout. To stay compatible with existing ABI
 (and API), it cannot support statically allocated Python objects.
 
 There is one type of object that is needed in most extension modules
-and is allocated statically in virtually cases: the ``PyModuleDef`` returned
+and is allocated statically in virtually all cases: the ``PyModuleDef`` returned
 from the module export hooks (that is, ``PyInit_*`` functions).
 
 Module export hooks (``PyInit_*`` functions) can return two kinds of objects:
@@ -48,12 +48,12 @@ Module export hooks (``PyInit_*`` functions) can return two kinds of objects:
    (Specifically, the *contents* of such a module's ``__dict__`` are shared
    across all instances of the module object.)
 
-   The modules to return is typically created using the ``PyModule_Create``
+   The module returned is typically created using the ``PyModule_Create``
    function, which requires a statically allocated (or at least long-lived)
    ``PyModuleDef`` struct.
 
    It is possible to bypass this using the lower-level ``PyModule_New*`` API.
-   This does not need ``PyModuleDef``, but offers much less functionality.
+   This avoids the need for ``PyModuleDef``, but offers much less functionality.
 
 2. A ``PyModuleDef`` object containing a description of how to create a module
    object. This option, *multi-phase initialization*, was introduced in
@@ -118,13 +118,13 @@ Python can check whether the module is compatible.
 Using slots without a wrapper struct
 ------------------------------------
 
-The existing ``PyModuleDef`` is struct with some fixed fields and
+The existing ``PyModuleDef`` is a struct with some fixed fields and
 a “slots” array.
 Unlike slots, the fixed fields cannot be individually deprecated and replaced.
 This proposal does away with fixed fields and proposes using a slots array
 directly, without a wrapper struct.
 
-The ``PyModuleDef_Slot`` struct does have some downsides to fixed fields.
+The ``PyModuleDef_Slot`` struct does have some downsides compared to fixed fields.
 We believe these are fixable, but leave that out of scope of this PEP
 (see “Improving slots in general” in the Possible Future Directions section).
 
@@ -144,14 +144,14 @@ This proposal adds the same mechanism to modules.
 
 Unlike types, the import mechanism often has a pointer that's known to be
 suitable as a token value; in these cases it can provide a default token.
-Thus, module tokens do not need a varaint of the inelegant ``Py_TP_USE_SPEC``.
+Thus, module tokens do not need a variant of the inelegant ``Py_TP_USE_SPEC``.
 
 
 Specification
 =============
 
 
-When importing an extension module, Python will newly look for an export hook
+When importing an extension module, Python will now first look for an export hook
 like this:
 
 .. code-block:: c
@@ -201,9 +201,8 @@ A new function will be added to create a module from an array of slots:
 
 The *slots* argument must point to an array of ``PyModuleDef_Slot`` structures,
 terminated by a slot with ``slot=0`` (typically written as ``{0}`` in C).
-There are no required slots.
-(So, the minimal input contains only the terminator; *slots* may not be
-``NULL``.)
+There are no required slots, though *slots* must not be ``NULL``.
+It follows that minimal input contains only the terminator slot.
 
 The *spec* argument is a duck-typed ModuleSpec-like object, meaning that any
 attributes defined for ``importlib.machinery.ModuleSpec`` have matching
@@ -230,9 +229,9 @@ As an exception, any ``PyMethodDef`` array given by ``Py_mod_methods``
 must be statically allocated (or be otherwise guaranteed to outlive the
 objects created from it). This limitation may be lifted in the future.
 
-A new function will be added to run the ``exec`` slot(s) for a module -- like
-``PyModule_ExecDef``, but supporting modules created using slots,
-and not taking an explicit *def*:
+A new function, ``PyModule_Exec``, will be added to run the ``exec`` slot(s) for a module.
+This acts like ``PyModule_ExecDef``, but supports modules created using slots,
+and does not take an explicit *def*:
 
 .. code-block:: c
 
@@ -254,15 +253,16 @@ similar to ``Py_tp_token`` for types.
 
 If specified, using a new ``Py_mod_token`` slot, the module token must:
 
-- outlive the module, so it’s not reused for something else while the module
+- outlive the module, so it's not reused for something else while the module
   exists; and
-- “belong” to the extension module where the module lives, so it will not
-  clash with other extensions.
+- "belong" to the extension module where the module lives, so it will not
+  clash with other extension modules.
 
 (Typically, it should point to a static constant.)
 
-Modules created using the new ``PyModule_FromSlotsAndSpec`` or the new
-export hook can use a slot with a new ID, ``Py_mod_token``, to set the token.
+Modules created using the ``PyModule_FromSlotsAndSpec`` or the
+``PyModExport_<NAME>`` export hook can use a new ``Py_mod_token`` slot
+to set the token.
 
 Modules created from a ``PyModuleDef`` will have the token set to that
 definition. An explicit ``Py_mod_token`` slot will we rejected for these.
@@ -435,7 +435,7 @@ Improving slots in general
 Slots -- and specifically the existing ``PyModuleDef_Slot`` -- do have a few
 shortcomings. The most important are:
 
-- Type safety: ``void *`` is used for data poiners, function pointers
+- Type safety: ``void *`` is used for data pointers, function pointers
   and small integers, requiring casting that is technically undefined
   behaviour in C -- but works in practice on all relevant architectures.
   (For example: ``Py_tp_doc`` marks a string; ``Py_mod_gil`` an integer.)
@@ -468,7 +468,6 @@ The inittab is used for embedding, where a common/stable ABI is not that
 important. So, it might be OK to leave this to a later change.
 
 
-
 Copyright
 =========