updates

Author: AA-Turner

Doc/c-api/allocation.rst

@@ -153,6 +153,6 @@ Allocating Objects on the Heap
 
 .. seealso::
 
-   :c:func:`PyModule_Create`
+   :ref:`moduleobjects`
       To allocate and create extension modules.
 

Doc/c-api/intro.rst

@@ -129,7 +129,6 @@ complete listing.
        static struct PyModuleDef spam_module = {
            .m_base = PyModuleDef_HEAD_INIT,
            .m_name = "spam",
-           .m_size = 0,
            ...
        };
 

Doc/extending/building.rst

@@ -23,10 +23,10 @@ instance. See :ref:`initializing-modules` for details.
 .. highlight:: python
 
 For modules with ASCII-only names, the function must be named
-``PyInit_<modulename>``, with ``<modulename>`` replaced by the name of the
-module. When using :ref:`multi-phase-initialization`, non-ASCII module names
+:samp:`PyInit_{<name>}`, with ``<name>`` replaced by the name of the module.
+When using :ref:`multi-phase-initialization`, non-ASCII module names
 are allowed. In this case, the initialization function name is
-``PyInitU_<modulename>``, with ``<modulename>`` encoded using Python's
+:samp:`PyInitU_{<name>}`, with ``<name>`` encoded using Python's
 *punycode* encoding with hyphens replaced by underscores. In Python::
 
     def initfunc_name(name):

Doc/extending/embedding.rst

@@ -251,7 +251,7 @@ Python extension.  For example::
        {NULL, NULL, 0, NULL}
    };
 
-   struct PyModuleDef emb_module = {
+   static struct PyModuleDef emb_module = {
        .m_base = PyModuleDef_HEAD_INIT,
        .m_name = "emb",
        .m_size = 0,

Doc/extending/extending.rst

@@ -203,24 +203,32 @@ function usually raises :c:data:`PyExc_TypeError`.  If you have an argument whos
 value must be in a particular range or must satisfy other conditions,
 :c:data:`PyExc_ValueError` is appropriate.
 
-You can also define a new exception that is unique to your module. For this, you
-usually declare a static object variable at the beginning of your file::
+You can also define a new exception that is unique to your module.
+For this, you usually declare an object variable at in the module state::
 
-   static PyObject *SpamError;
+   typedef struct {
+       // ...
+       PyObject *SpamError;
+       // ...
+   } spam_state;
 
 and initialize it in the module's :c:data:`Py_mod_exec` function
-(:c:func:`!spam_module_exec`)
-
-with an exception object::
+(:c:func:`!spam_module_exec`) with an exception object::
 
    static int
    spam_module_exec(PyObject *m)
    {
-       SpamError = PyErr_NewException("spam.error", NULL, NULL);
-       if (PyModule_AddObjectRef(m, "SpamError", SpamError) < 0) {
+       spam_state *state = PyModule_GetState(m);
+       if (state == NULL) {
+           return -1;
+       }
+       state->SpamError = PyErr_NewException("spam.error", NULL, NULL);
+       if (state->SpamError == NULL) {
+           return -1;
+       }
+       if (PyModule_AddType(m, (PyTypeObject *)state->SpamError) < 0) {
            return -1;
        }
-
        return 0;
    }
 
@@ -232,7 +240,7 @@ with an exception object::
    static struct PyModuleDef spam_module = {
        .m_base = PyModuleDef_HEAD_INIT,
        .m_name = "spam",
-       .m_size = 0,  // non-negative
+       .m_size = sizeof(spam_state),
        .m_slots = spam_module_slots,
    };
 
@@ -436,18 +444,20 @@ optionally followed by an import of the module::
 
 .. note::
 
-   If you declare a global variable or a local static one, the module can
-   cause the same problems as the legacy single-phase initialization when
+   If you declare a global variable or a local static one, the module may
+   experience unintended side-effects on re-initialisation, for example when
    removing entries from ``sys.modules`` or importing compiled modules into
-   multiple interpreters within a process (or following a :c:func:`fork` without an
-   intervening :c:func:`exec`).  In this case, at least the module should
-   stop supporting subinterpreters through a :c:type:`PyModuleDef_Slot`
-   (:c:data:`Py_mod_multiple_interpreters`).
+   multiple interpreters within a process
+   (or following a :c:func:`fork` without an intervening :c:func:`exec`).
+   If module state is not yet fully :ref:`isolated <isolating-extensions-howto>`,
+   authors should consider marking the module as having no support for subinterpreters
+   (via :c:macro:`Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED`).
 
 A more substantial example module is included in the Python source distribution
 as :file:`Modules/xxlimited.c`.  This file may be used as a template or simply
 read as an example.
 
+
 .. _compilation:
 
 Compilation and Linkage
@@ -1068,8 +1078,9 @@ why his :meth:`!__del__` methods would fail...
 
 The second case of problems with a borrowed reference is a variant involving
 threads.  Normally, multiple threads in the Python interpreter can't get in each
-other's way, because there is a global lock protecting Python's entire object
-space.  However, it is possible to temporarily release this lock using the macro
+other's way, because there is a :term:`global lock <global interpreter lock>`
+protecting Python's entire object space.
+However, it is possible to temporarily release this lock using the macro
 :c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using
 :c:macro:`Py_END_ALLOW_THREADS`.  This is common around blocking I/O calls, to
 let other threads use the processor while waiting for the I/O to complete.
@@ -1255,8 +1266,8 @@ two more lines must be added::
    #include "spammodule.h"
 
 The ``#define`` is used to tell the header file that it is being included in the
-exporting module, not a client module. Finally, the module's initialization
-function must take care of initializing the C API pointer array::
+exporting module, not a client module. Finally, the module's :c:data:`mod_exec
+<Py_mod_exec>` function must take care of initializing the C API pointer array::
 
    static int
    spam_module_exec(PyObject *m)
@@ -1277,24 +1288,6 @@ function must take care of initializing the C API pointer array::
        return 0;
    }
 
-   static PyModuleDef_Slot spam_module_slots[] = {
-       {Py_mod_exec, spam_module_exec},
-       {0, NULL}
-   };
-
-   static struct PyModuleDef spam_module = {
-       .m_base = PyModuleDef_HEAD_INIT,
-       .m_name = "spam",
-       .m_size = 0,
-       .m_slots = spam_module_slots,
-   };
-
-   PyMODINIT_FUNC
-   PyInit_spam(void)
-   {
-       return PyModuleDef_Init(&spam_module);
-   }
-
 Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
 array would disappear when :c:func:`!PyInit_spam` terminates!
 
@@ -1351,7 +1344,7 @@ like this::
 
 All that a client module must do in order to have access to the function
 :c:func:`!PySpam_System` is to call the function (or rather macro)
-:c:func:`!import_spam` in its initialization function::
+:c:func:`!import_spam` in its :c:data:`mod_exec <Py_mod_exec>` function::
 
    static int
    client_module_exec(PyObject *m)
@@ -1362,24 +1355,6 @@ All that a client module must do in order to have access to the function
        return 0;
    }
 
-   static PyModuleDef_Slot client_module_slots[] = {
-       {Py_mod_exec, client_module_exec},
-       {0, NULL}
-   };
-
-   static struct PyModuleDef client_module = {
-       .m_base = PyModuleDef_HEAD_INIT,
-       .m_name = "client",
-       .m_size = 0,
-       .m_slots = client_module_slots,
-   };
-
-   PyMODINIT_FUNC
-   PyInit_client(void)
-   {
-       return PyModuleDef_Init(&client_module);
-   }
-
 The main disadvantage of this approach is that the file :file:`spammodule.h` is
 rather complicated. However, the basic structure is the same for each function
 that is exported, so it has to be learned only once.

Doc/extending/newtypes_tutorial.rst

@@ -55,8 +55,10 @@ from the previous chapter.  This file defines three things:
 #. How the :class:`!Custom` **type** behaves: this is the ``CustomType`` struct,
    which defines a set of flags and function pointers that the interpreter
    inspects when specific operations are requested.
-#. How to initialize the :mod:`!custom` module: this is the ``PyInit_custom``
-   function and the associated ``custommodule`` struct.
+#. How to define and execute the :mod:`!custom` module: this is the
+   ``PyInit_custom`` function and the associated ``custom_module`` struct for
+   defining the module, and the ``custom_module_exec`` function to set up
+   a fresh module object.
 
 The first bit is::
 
@@ -173,8 +175,9 @@ implementation provided by the API function :c:func:`PyType_GenericNew`. ::
 Everything else in the file should be familiar, except for some code in
 :c:func:`!custom_module_exec`::
 
-   if (PyType_Ready(&CustomType) < 0)
+   if (PyType_Ready(&CustomType) < 0) {
        return -1;
+   }
 
 This initializes the :class:`!Custom` type, filling in a number of members
 to the appropriate default values, including :c:member:`~PyObject.ob_type` that we initially

Doc/includes/newtypes/custom.c

@@ -19,8 +19,9 @@ static PyTypeObject CustomType = {
 static int
 custom_module_exec(PyObject *m)
 {
-    if (PyType_Ready(&CustomType) < 0)
+    if (PyType_Ready(&CustomType) < 0) {
         return -1;
+    }
 
     if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
         return -1;

Doc/includes/newtypes/custom2.c

@@ -109,8 +109,9 @@ static PyTypeObject CustomType = {
 static int
 custom_module_exec(PyObject *m)
 {
-    if (PyType_Ready(&CustomType) < 0)
+    if (PyType_Ready(&CustomType) < 0) {
         return -1;
+    }
 
     if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
         return -1;

Doc/includes/newtypes/custom3.c

@@ -154,8 +154,9 @@ static PyTypeObject CustomType = {
 static int
 custom_module_exec(PyObject *m)
 {
-    if (PyType_Ready(&CustomType) < 0)
+    if (PyType_Ready(&CustomType) < 0) {
         return -1;
+    }
 
     if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
         return -1;

Doc/includes/newtypes/custom4.c

@@ -173,8 +173,9 @@ static PyTypeObject CustomType = {
 static int
 custom_module_exec(PyObject *m)
 {
-    if (PyType_Ready(&CustomType) < 0)
+    if (PyType_Ready(&CustomType) < 0) {
         return -1;
+    }
 
     if (PyModule_AddObjectRef(m, "Custom", (PyObject *) &CustomType) < 0) {
         return -1;