PEP 3121 suggests a new way of Module-initialization, where the module state is being wrapped inside a dedicate struct, which can be accessed at runtime via the PyState_FindModule method. For code outside the Init-method, there is no other way to receive the module-state, as it has no reference to the object created by PyModule_Create.
PyState_FindModule requires, that the module-state has been attached to the interpreter-state beforehand. Inside an extension module code this is almost everywhere the case except inside the Init-method, because currently _PyState_AddModule is only called by the importer AFTER the extension module has been initialized successfully. As most of the macro definitions inside an extension module, which rely on data stored in the module state, have to receive the state via FindModule, they fail to work inside the modules Init-method.

This patch suggests an extension of PyState comprising two publicly available methods (PyState_AddModule, PyState_RemoveModule) that can be called from inside the Init-method, so that the module-state is attached to the interpreter state before further initialization of the module continues. As a result, PyState_FindModule will also work in this region of the extension module and the bespoken expanded macros will also work flawlessly when executed inside the Init code.

This patch is especially important for the future application of PEP 3121 together with PEP 384, as the newly created heap-types now reside inside the module-state. As type-objects are frequently used in macro-definitions which are also expanded within the Init-method of a module (or inside a function called from Init), the module state has to be received via FindModule. (The alternative would be nasty redefinitions of the specific macros, shortly before Init)

These functions need to be documented.

Added missing documentation. Also added documentation of PyState_FindModule() which still happened to be missing.

New changeset 55e8cba34b11 by Martin v. Löwis in branch 'default':
Issue #15042: Add PyState_AddModule and PyState_RemoveModule.
http://hg.python.org/cpython/rev/55e8cba34b11

Thanks for the patch!