gh-157384: Document and test PyImport_CreateModuleFromInitfunc() semantics

[itamaro]

Document that single-phase init modules are added to sys.modules by the call itself (unlike multi-phase init modules), and that the spec name identifies the module, so a later call with the same name and a different init function reuses the cached module without calling the new init function. Add regression tests for both behaviors.

AI assisted with Claude Fable 5.1

• Issue: PyImport_CreateModuleFromInitfunc(): wrong __name__ for submodules, non-ASCII names rejected, inittab name clashes #157384

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35163548 | 📁 Comparing 27b9d61 against main (2cd6d4b)

  🔍 Preview build  

147 files changed · + 8 added · ± 139 modified

+ Added

• builtins/constants.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/index.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• builtins/time-complexity.html
• library/tkinter.dialogs.html

± Modified

• glossary.html
• index.html
• license.html
• _static/tachyon-example-heatmap.html
• c-api/bytearray.html
• c-api/bytes.html
• c-api/capsule.html
• c-api/complex.html
• c-api/exceptions.html
• c-api/extension-modules.html
• and 129 more...

[encukou]

Could you turn “legacy single-phase initialization” into a link? (And remove the parenthesis -- PyModule_Create is just an example.)

Also, please link the “as is done for”/“as for” parts -- the docs for the mentioned feature should explain what happens in more detail; if they don't then the mention isn't very useful.

The existing docs already point out that the init function is not called twice. It would be nice to clarify there what the “lookup key“ is when determining subsequent imports of the “same” module.

[itamaro]

Done, thanks for the suggestions @encukou !

[encukou]

I'll rebase, and reword a bit.

[encukou]

@itamaro, how's this look?

[itamaro]

@itamaro, how's this look?

Thanks @encukou , this reads much better than what I had! the merge looks good too.

should we make the collision case more accurate? in two places (extension-modules.rst from my commits and import.rst in your commit) we're explaining how initfunc is not called again on name collision, but this is technically correct only for builtins and inittab extensions (and modules created through PyImport_CreateModuleFromInitfunc) - those can't collide with .so-file-based extensions (the path is part of the cache key).

possible changes:

• If a single-phase module was previously created under the same name by this function or as a built-in module (e.g. one registered with PyImport_AppendInittab), including in another interpreter, Python does not call initfunc again...

and for extension-modules.rst: "Modules are matched to the saved contents by the module's full dotted name (and, for extensions loaded from a file, the file's path)".

another nit: "reuses the previous module's contents" is only accurate for m_size == -1. For m_size >= 0, the behavior depends on which interpreter loaded the module first (it may re-run the first cached init function, or call the new one). not sure how deeply we want to document that. maybe a short "for modules with m_size of -1" qualifier, or just rely on the "implementation detail" framing. wdyt?

happy to push the changes if you'd like.

[encukou]

Hm, right. I guess it makes sense to document this, especially since it's soft-deprecated and thus should not change.
We get a wall of text full of weird edge cases; rather than “how to use this” it tells you “why you shouldn't use single-phase init”.

I still left out the subinterpreter-specific behaviour, saying it could go either way.

Does this look good?

Please feel free to push directly, it's your PR :)