Repository navigation
Docs Examples Focus on Outdated Single-Phase Init Modules and Static Types #134160
Description
A variety of pages show examples (or provide explanations) around single-phase init modules and static types, but should focus on the newer, recommended alternatives. For example:
- https://docs.python.org/3/extending/extending.html#intermezzo-errors-and-exceptions
https://github.com/python/cpython/blob/main/Doc/extending/extending.rst?plain=1#L206-L265 - https://docs.python.org/3/extending/extending.html#the-module-s-method-table-and-initialization-function
https://github.com/python/cpython/blob/main/Doc/extending/extending.rst?plain=1#L355-L379 - https://docs.python.org/3/extending/newtypes_tutorial.html
https://github.com/python/cpython/blob/main/Doc/extending/newtypes_tutorial.rst - https://docs.python.org/3/extending/newtypes.html
https://github.com/python/cpython/blob/main/Doc/extending/newtypes.rst - https://docs.python.org/3/extending/embedding.html#extending-embedded-python
https://github.com/python/cpython/blob/main/Doc/extending/embedding.rst?plain=1#L225
For reference:
- https://docs.python.org/3/howto/isolating-extensions.html#isolating-extensions-howto
- https://docs.python.org/3/c-api/module.html
- https://docs.python.org/3/c-api/type.html#creating-heap-allocated-types
Linked PRs
- gh-134160: Use multi-phase init in documentation examples #134296
- [3.14] gh-134160: Use multi-phase init in documentation examples (GH-134296) #134753
- [3.13] gh-134160: Use multi-phase init in documentation examples (GH-134296) #134754
- GH-134160: Prefer multi-phase initialisation in docs #134764
- gh-134160: Block multiple module initialization #134773
- gh-134160: Improve multi-phase init note on isolation & subinterpreters #134775
- [3.14] gh-134160: Block multiple module initialization (GH-134773) #134827
- [3.13] gh-134160: Block multiple module initialization (GH-134773) #134828
- [3.14] gh-134160: Improve multi-phase init note on isolation & subinterpreters (GH-134775) #134932
- [3.13] gh-134160: Improve multi-phase init note on isolation & subinterpreters (GH-134775) #134983
- gh-134160: Split extension module init from PyModule docs; emphasize multi-phase init #135126
- gh-134160: Use PyModuleDef.m_free in the example module xxlimited #135174
- [3.14] gh-134160: Use PyModuleDef.m_free in the example module xxlimited (GH-135174) #135213
- [3.13] gh-134160: Use PyModuleDef.m_free in the example module xxlimited (GH-135174) #135214
- [3.14] gh-134160: Split extension module init from PyModule docs; emphasize multi-phase init (GH-135126) #135470
- gh-134160: Add more comments for the xxlimited module #140214
- [3.14] gh-134160: Add more comments for the xxlimited module (GH-140214) #140664
- gh-134160: Start "Extending and embedding" with a Diataxis-style tutorial #142314
- gh-134160: "First extension module" tutorial improvements #144183
Activity
neonene commentedon May 19, 2025
cpython/Doc/extending/extending.rst
Lines 446 to 451 in 9983c7d
Should alternatives be explained according to
xxmodule? I'm not sure what "xx" officially means, though. Or, maybenew, leaving/removing the legacy page andeggsexamplesxxmodule.c?ericsnowcurrently commentedon May 21, 2025
Good point. I'm not quite sure. Keeping the old tutorials around makes sense in some ways, but perhaps not in a different file somehow or maybe just not listed in the index?
As to the
xxmoduleit may make sense to add a new equivalent for multi-phase init. @encukou might have some thoughts on this.ericsnowcurrently commentedon May 21, 2025
Ideally we would update the docs back to 3.12 at least.
encukou commentedon May 21, 2025
Thank you for doing this! Sorry that I can't give this my full attention right now.
xxmodule: Usexxlimitedinstead.Backporting: AFAIK, stats show that most people go to the current version. IMO, at this point, backporting big changes to 3.14 is fine.
gh-134160: Use multi-phase init in documentation examples (#134296)
pythongh-134160: Use multi-phase init in documentation examples (pyth…
pythongh-134160: Use multi-phase init in documentation examples (pyth…
[3.14] gh-134160: Use multi-phase init in documentation examples (GH-…
[3.13] gh-134160: Use multi-phase init in documentation examples (GH-…
encukou commentedon May 27, 2025
The docs are now incorrect :(
I'm sorry that I missed the review window; I was planning to take a look next week but didn't announce that.
Would it make sense to revert the 3.13 backport at least?
pythongh-134160: Block multiple module initialization
pythongh-134160: Block multiple initialization & note reference leak
41 remaining items
Add Py_tp_token support to xxlimited module
Add Py_tp_token support to xxlimited module
Add Py_tp_token support to xxlimited module
Add Py_tp_token support to xxlimited module
encukou commentedon Dec 5, 2025
Here's a big one: #142314
pythongh-134160: Add more comments for the xxlimited module (pythonGH…
gh-134160: Start "Extending and embedding" with a Diataxis-style tuto…
pythongh-134160: Start "Extending and embedding" with a Diataxis-styl…
pythongh-134160: "First extension module" tutorial improvements
gh-134160: "First extension module" tutorial improvements (GH-144183)
pythongh-134160: "First extension module" tutorial improvements (pyth…
pythongh-134160: "First extension module" tutorial improvements (pyth…
pythongh-134160: Use multi-phase init in documentation examples (pyth…
pythongh-134160: Block multiple module initialization (python#134773)
pythongh-134160: Improve multi-phase init note on isolation & subinte…