gh-134160: Use multi-phase init in documentation examples

[neonene]

Replaces PyModule_Create() with PyModuleDef_Init().

Static types still remain unchanged in the doc.

• Issue: Docs Examples Focus on Outdated Single-Phase Init Modules and Static Types #134160

---

📚 Documentation preview 📚: https://cpython-previews--134296.org.readthedocs.build/

[neonene]

cc @erlend-aasland@encukou Just in case you're interested.

[AA-Turner]

Having done trial conversions of NumPy to multi-phase, I think we should include the relevant PY_VERSION_HEX checks. Both Py_mod_multiple_interpreters and Py_mod_gil were added very recently.

If we agree on adding these checks, we should add them for all relevant PyModuleDef_Slot structs. It is verbose, but aids in the copy-and-paste scenario.

Suggested change

	static PyModuleDef_Slot emb_module_slots[] = {
	{Py_mod_multiple_interpreters, Py_MOD_PER_INTERPRETER_GIL_SUPPORTED},
	{Py_mod_gil, Py_MOD_GIL_NOT_USED},
	{0, NULL}
	};
	static PyModuleDef_Slot emb_module_slots[] = {
	#if PY_VERSION_HEX >= 0x030C00F0 // Python 3.12+
	// signal that this module can be imported in isolated subinterpreters
	{Py_mod_multiple_interpreters, Py_MOD_PER_INTERPRETER_GIL_SUPPORTED},
	#endif
	#if PY_VERSION_HEX >= 0x030D00F0 // Python 3.13+
	// signal that this module supports running without an active GIL
	{Py_mod_gil, Py_MOD_GIL_NOT_USED},
	#endif
	{0, NULL}
	};

[AA-Turner]

Alternative:

Suggested change

	static PyModuleDef_Slot emb_module_slots[] = {
	{Py_mod_multiple_interpreters, Py_MOD_PER_INTERPRETER_GIL_SUPPORTED},
	{Py_mod_gil, Py_MOD_GIL_NOT_USED},
	{0, NULL}
	};
	static PyModuleDef_Slot emb_module_slots[] = {
	#ifdef Py_mod_multiple_interpreters
	// signal that this module can be imported in isolated subinterpreters
	{Py_mod_multiple_interpreters, Py_MOD_PER_INTERPRETER_GIL_SUPPORTED},
	#endif
	#ifdef Py_mod_gil
	// signal that this module supports running without an active GIL
	{Py_mod_gil, Py_MOD_GIL_NOT_USED},
	#endif
	{0, NULL}
	};

[encukou]

Can this PR omit these slots entirely?

IMO, they should be introduced later, after you compile your first module, along with a longer discussion about isolated state & thread safety.

[AA-Turner]

Agree better to keep simple. @neonene perhaps remove the gil and interpreter slots from where we've added them in this PR unless they were already present?

[neonene]

Removed, but not all. I can complete.

[AA-Turner]

Other places to update:

• https://cpython-previews--134296.org.readthedocs.build/en/134296/c-api/allocation.html: PyModule_Create() To allocate and create extension modules. Should point to multi-phase modules & note PyModule_Create is for static.
• https://cpython-previews--134296.org.readthedocs.build/en/134296/howto/free-threading-extensions.html#single-phase-initialization Should suggest adopting multi-phase with no isolation before describing the PyUnstable function, perhaps link to the porting guide
• https://cpython-previews--134296.org.readthedocs.build/en/134296/c-api/module.html#initializing-c-modules Mention multi-phase before PyModule_Create

[neonene]

One of my motivation: https://discuss.python.org/t/proposal-officially-deprecate-support-for-legacy-single-phase-init-extension-modules/89262/26

[miss-islington-app]

Thanks @neonene for the PR, and @AA-Turner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-app]

GH-134753 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-134754 is a backport of this pull request to the 3.13 branch.

[encukou]

This is not correct for multi-phase initialization, without preventing the exec function from other module instances from overriding this pointer.

[AA-Turner]

@encukou I added but then reverted (6e5b1c5) module state for this error type -- should we un-revert that commit? Sorry for my mistake here.

A

[encukou]

I think it's fine -- module state deserves a better explanation a bit later in the tutorial. And the ImportError being added in the next PR is a good thing to show.

The main thing I'd do differently is not backporting to 3.13 -- that's like pushing directly to production. 3.14 is out in a few months; that sounds like a good amount of time for this all to spend in prerelease.