gh-134160: Use multi-phase init in documentation examples by neonene · Pull Request #134296 · python/cpython · GitHub

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/

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

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

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}
          
               };

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}
          
               };

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.

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?

Removed, but not all. I can complete.

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

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

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

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!

…onGH-134296) (cherry picked from commit 96905bd) Co-authored-by: neonene <53406459+neonene@users.noreply.github.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

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

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

…134296) (#134753) gh-134160: Use multi-phase init in documentation examples (GH-134296) (cherry picked from commit 96905bd) Co-authored-by: neonene <53406459+neonene@users.noreply.github.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

…134296) (#134754) gh-134160: Use multi-phase init in documentation examples (GH-134296) (cherry picked from commit 96905bd) Co-authored-by: neonene <53406459+neonene@users.noreply.github.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

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

@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

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.

…on#134296) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Update docs

8d8b366

bedevere-app Bot mentioned this pull request May 19, 2025

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

Open

bedevere-app Bot added the awaiting review label May 19, 2025

Don't change an unrelated example

88c5f3f

AA-Turner changed the title gh-134160: Docs: Ensure single-phase init is no longer used in examples gh-134160: Use multi-phase init in documentation examples May 21, 2025

AA-Turner added the docs Documentation in the Doc dir label May 21, 2025

github-project-automation Bot added this to Docs PRs May 21, 2025

github-project-automation Bot moved this to Todo in Docs PRs May 21, 2025

AA-Turner added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels May 21, 2025

AA-Turner requested a review from ericsnowcurrently May 21, 2025 00:01

AA-Turner reviewed May 21, 2025

View reviewed changes

neonene and others added 11 commits May 21, 2025 18:43

Apply suggestions from code review

a4ade5c

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

ditto

d6c42e2

Suggested module names

97eae13

Avoid modernization

8ae6bae

typo

bc78288

Correction: "error"

c3ab022

Rephrase warning

d65303c

keywdarg_module

aec6781

Update Doc/extending/extending.rst

7dfd5ad

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Indicate xxlimited

f7c72dd

Add seealso to index

c84638c

AA-Turner reviewed May 22, 2025

View reviewed changes

AA-Turner added the skip news label May 22, 2025

neonene and others added 3 commits May 22, 2025 16:05

Update Doc/extending/embedding.rst

4e59e88

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

ditto (for copy-paste)

d68e3e3

Shrink slots

f6465bd

neonene added 3 commits May 23, 2025 07:10

Correction: "SpamError"

a83e266

Add a Py_mod_multiple_interpreters slot

2d10958

Cancel the prvious addition as needless

a28e67c

AA-Turner added 3 commits May 26, 2025 20:26

Merge remote-tracking branch 'upstream/main' into multi

9e6bff5

updates

d35a6b4

PEP 7

9cb3092

AA-Turner approved these changes May 26, 2025

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels May 26, 2025

revert module state for SpamError

6e5b1c5

AA-Turner enabled auto-merge (squash) May 26, 2025 21:39

AA-Turner merged commit 96905bd into python:main May 26, 2025

github-project-automation Bot moved this from Todo to Done in Docs PRs May 26, 2025

bedevere-app Bot removed the awaiting merge label May 26, 2025

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label May 26, 2025

bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label May 26, 2025

AA-Turner mentioned this pull request May 27, 2025

GH-134160: Prefer multi-phase initialisation in docs #134764

Closed

encukou reviewed May 27, 2025

View reviewed changes

neonene deleted the multi branch May 27, 2025 05:48

Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025

pythongh-134160 : Use multi-phase init in documentation examples (pyth…

cfecd06

…on#134296) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025

pythongh-134160 : Use multi-phase init in documentation examples (pyth…

2ea7d29

…on#134296) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

gostak-dd pushed a commit to gostak-dd/cpython that referenced this pull request Jun 2, 2026

pythongh-134160 : Use multi-phase init in documentation examples (pyth…

9a68024

…on#134296) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

+              You can also define a new exception that is unique to your module.
+              For this, you can declare a static global object variable at the beginning
+              of the file::

gh-134160: Use multi-phase init in documentation examples by neonene · Pull Request #134296 · python/cpython · GitHub

Uh oh!

Uh oh!

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

gh-134160: Use multi-phase init in documentation examples#134296AA-Turner merged 24 commits intopython:mainpython/cpython:mainfrom neonene:multineonene/cpython:multiCopy head branch name to clipboard

Conversation

neonene commented May 19, 2025 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neonene commented May 20, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AA-Turner May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner May 22, 2025

Choose a reason for hiding this comment

Uh oh!

encukou May 22, 2025

Choose a reason for hiding this comment

Uh oh!

AA-Turner May 22, 2025

Choose a reason for hiding this comment

Uh oh!

neonene May 22, 2025

Choose a reason for hiding this comment

Uh oh!

AA-Turner commented May 22, 2025

Uh oh!

neonene commented May 22, 2025

Uh oh!

miss-islington-app Bot commented May 26, 2025

Uh oh!

bedevere-app Bot commented May 26, 2025

Uh oh!

bedevere-app Bot commented May 26, 2025

Uh oh!

encukou May 27, 2025

Choose a reason for hiding this comment

Uh oh!

AA-Turner May 27, 2025

Choose a reason for hiding this comment

Uh oh!

encukou May 27, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gh-134160: Use multi-phase init in documentation examples#134296
AA-Turner merged 24 commits into
python:mainfrom
neonene:multi

neonene commented May 19, 2025 •
edited by github-actions Bot
Loading

AA-Turner May 22, 2025 •
edited
Loading