Add a backwards-compatibility shim for PyInit

Author: encukou

peps/pep-0793.rst

@@ -412,6 +412,9 @@ Here is a guide to convert an existing module to the new API, including
 some tricky edge cases.
 It should be moved to a HOWTO in the documentation.
 
+This guide is meant for hand-written modules. For code generators and language
+wrappers, the :ref:`pep793-shim` below may be more useful.
+
 #. Scan your code for uses of ``PyModule_GetDef``. This function will
    return ``NULL`` for modules that use the new mechanism. Instead:
 
@@ -493,6 +496,40 @@ Once your module no longer supports lower versions, delete the ``PyInit_``
 function and any unused data.
 
 
+Backwards compatibility shim
+----------------------------
+
+It is possible to write generic function that implements the existing export
+hook (``PyInit_``) in terms of the API proposed here.
+
+The following implemntation can be copy-pasted; only the names
+``PyInit_examplemodule`` (twice) and ``PyModExport_examplemodule`` need adjusting.
+
+When added to the :ref:`pep793-example` below and compiled with a
+non-free-threaded build of this PEP's reference implementation, the resulting
+extension is compatible with regular builds 3.9+ in addition to a
+free-threading build of the reference implementation.
+(The module must be named without a version tag, e.g. ``examplemodule.so``,
+and be placed on ``sys.path``.)
+
+Full support for creating such modules will require backports of some new
+API, and support in build/install tools. This is out of scope of this PEP.
+(In particular, the demo “cheats” uses a subset Limited API 3.15 that
+*happens to work* on 3.9; it *should* use Limited API 3.9 with backport
+shims for new API like ``Py_mod_name``.)
+
+This implementation places a few additional requirements on the slots array:
+
+- Slots that correspond to ``PyModuleDef`` members must come first.
+- A ``Py_mod_name`` slot is required.
+- Any ``Py_mod_token`` must be set to ``&module_def_and_token``, defined here.
+
+It also passes ``NULL`` as *spec* to the ``PyModExport`` export hook.
+A proper implementation would pass ``None`` instead, .
+
+.. literalinclude:: pep-0793/shim.c
+   :language: c
+
 
 Security Implications
 =====================
@@ -507,6 +544,8 @@ In addition to regular reference docs, the :ref:`pep793-porting-notes` should
 be added as a new HOWTO.
 
 
+.. _pep793-example:
+
 Example
 =======
 

peps/pep-0793/examplemodule.c

@@ -49,9 +49,9 @@ PyDoc_STRVAR(examplemodule_doc, "Example extension.");
 static PyModuleDef_Slot examplemodule_slots[] = {
     {Py_mod_name, "examplemodule"},
     {Py_mod_doc, (char*)examplemodule_doc},
-    {Py_mod_exec, (void*)examplemodule_exec},
     {Py_mod_methods, examplemodule_methods},
     {Py_mod_state_size, (void*)sizeof(examplemodule_state)},
+    {Py_mod_exec, (void*)examplemodule_exec},
     {0}
 };
 

peps/pep-0793/shim.c

@@ -0,0 +1,68 @@
+#include <string.h>     // memset
+
+PyMODINIT_FUNC PyInit_examplemodule(void);
+
+static PyModuleDef module_def_and_token;
+
+PyMODINIT_FUNC
+PyInit_examplemodule(void)
+{
+    PyModuleDef_Slot *slot = PyModExport_examplemodule(NULL);
+
+    if (module_def_and_token.m_name) {
+        // Take care to only set up the static PyModuleDef once.
+        // (PyModExport might theoretically return different data each time.)
+        return PyModuleDef_Init(&module_def_and_token);
+    }
+    int copying_slots = 1;
+    for (/* slot set above */; slot->slot; slot++) {
+        switch (slot->slot) {
+        // Set PyModuleDef members from slots. These slots must come first.
+#       define COPYSLOT_CASE(SLOT, MEMBER, TYPE)                            \
+            case SLOT:                                                      \
+                if (!copying_slots) {                                       \
+                    PyErr_SetString(PyExc_SystemError,                      \
+                                    #SLOT " must be specified earlier");    \
+                    goto error;                                             \
+                }                                                           \
+                module_def_and_token.MEMBER = (TYPE)(slot->value);          \
+                break;                                                      \
+            /////////////////////////////////////////////////////////////////
+        COPYSLOT_CASE(Py_mod_name, m_name, char*)
+        COPYSLOT_CASE(Py_mod_doc, m_doc, char*)
+        COPYSLOT_CASE(Py_mod_state_size, m_size, Py_ssize_t)
+        COPYSLOT_CASE(Py_mod_methods, m_methods, PyMethodDef*)
+        COPYSLOT_CASE(Py_mod_state_traverse, m_traverse, traverseproc)
+        COPYSLOT_CASE(Py_mod_state_clear, m_clear, inquiry)
+        COPYSLOT_CASE(Py_mod_state_free, m_free, freefunc)
+        case Py_mod_token:
+            // With PyInit_, the PyModuleDef is used as the token.
+            if (slot->value != &module_def_and_token) {
+                PyErr_SetString(PyExc_SystemError,
+                                "Py_mod_token must be set to "
+                                "&module_def_and_token");
+                goto error;
+            }
+            break;
+        default:
+            // The remaining slots become m_slots in the def.
+            // (`slot` now points to the "rest" of the original
+            //  zero-terminated array.)
+            if (copying_slots) {
+                module_def_and_token.m_slots = slot;
+            }
+            copying_slots = 0;
+            break;
+        }
+    }
+    if (!module_def_and_token.m_name) {
+        // This function needs m_name as the "is initialized" marker.
+        PyErr_SetString(PyExc_SystemError, "Py_mod_name slot is required");
+        goto error;
+    }
+    return PyModuleDef_Init(&module_def_and_token);
+
+error:
+    memset(&module_def_and_token, 0, sizeof(module_def_and_token));
+    return NULL;
+}