Description

ericsnowcurrently

opened on May 17, 2025

Issue body actions

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

Reacted by Adam Turner, Ralf Gommers and Petr Viktorin

Activity

1. ericsnowcurrently

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on May 17, 2025
2. github-project-automation

   added this to docs issueson May 17, 2025
3. github-project-automation

   moved this to Todo in docs issueson May 17, 2025
4. neonene commented on May 19, 2025

   

   neonene

   on May 19, 2025

   Contributor

   More actions

   cpython/Doc/extending/extending.rst

   Lines 446 to 451 in 9983c7d

   	.. note::
   	Unlike our ``spam`` example, ``xxmodule`` uses *multi-phase initialization*
   	(new in Python 3.5), where a PyModuleDef structure is returned from
   	``PyInit_spam``, and creation of the module is left to the import machinery.
   	For details on multi-phase initialization, see :PEP:`489`.

   Should alternatives be explained according to xxmodule? I'm not sure what "xx" officially means, though. Or, maybe new eggs examples, leaving/removing the legacy page and xxmodule.c?
5. ericsnowcurrently commented on May 21, 2025

   

   ericsnowcurrently

   on May 21, 2025

   MemberAuthor

   More actions

   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 xxmodule it may make sense to add a new equivalent for multi-phase init. @encukou might have some thoughts on this.
6. ericsnowcurrently commented on May 21, 2025

   

   ericsnowcurrently

   on May 21, 2025

   MemberAuthor

   More actions

   Ideally we would update the docs back to 3.12 at least.
7. encukou commented on May 21, 2025

   

   encukou

   on May 21, 2025

   Member

   More actions

   Thank you for doing this! Sorry that I can't give this my full attention right now.

   xxmodule: Use xxlimited instead.
   Backporting: AFAIK, stats show that most people go to the current version. IMO, at this point, backporting big changes to 3.14 is fine.
8. AA-Turner

   added a commit that references this issue on May 26, 2025

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

   96905bd
9. miss-islington

   added 2 commits that reference this issue on May 26, 2025

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

   f6398e2

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

   0930d33
10. AA-Turner

    added 2 commits that reference this issue on May 26, 2025

    [3.14] gh-134160: Use multi-phase init in documentation examples (GH-…

    b6e624a

    [3.13] gh-134160: Use multi-phase init in documentation examples (GH-…

    480f02d
11. encukou commented on May 27, 2025

    

    encukou

    on May 27, 2025

    Member

    More actions

    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?
12. encukou

    added 2 commits that reference this issue on May 27, 2025

    pythongh-134160: Block multiple module initialization

    d6a33c4

    pythongh-134160: Block multiple initialization & note reference leak

    a5292df
13. 42 remaining items
14. gpshead

    added 3 commits that reference this issue on Nov 17, 2025

    Add Py_tp_token support to xxlimited module

    3e06b4f

    Add Py_tp_token support to xxlimited module

    d9613e0

    Add Py_tp_token support to xxlimited module

    93b525f
15. encukou commented on Dec 5, 2025

    

    encukou

    on Dec 5, 2025

    Member

    More actions

    Here's a big one: #142314
16. StanFromIreland

    added a commit that references this issue on Dec 6, 2025

    pythongh-134160: Add more comments for the xxlimited module (pythonGH…

    8a2fe8f
17. encukou

    added a commit that references this issue on Dec 19, 2025

    gh-134160: Start "Extending and embedding" with a Diataxis-style tuto…

    049c252
18. cocolato

    added a commit that references this issue on Dec 22, 2025

    pythongh-134160: Start "Extending and embedding" with a Diataxis-styl…

    ca1dc21
19. encukou

    added a commit that references this issue on Jan 23, 2026

    pythongh-134160: "First extension module" tutorial improvements

    5de2f0b
20. encukou

    added a commit that references this issue on Feb 2, 2026

    gh-134160: "First extension module" tutorial improvements (GH-144183)

    afc2aeb
21. Aniketsy

    added a commit that references this issue on Feb 3, 2026

    pythongh-134160: "First extension module" tutorial improvements (pyth…

    b9a7530
22. thunder-coding

    added a commit that references this issue on Feb 15, 2026

    pythongh-134160: "First extension module" tutorial improvements (pyth…

    f241849
23. gostak-dd

    added 3 commits that reference this issue on Jun 2, 2026

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

    9a68024

    pythongh-134160: Block multiple module initialization (python#134773)

    b49a480

    pythongh-134160: Improve multi-phase init note on isolation & subinte…

    0fd850e
24. ambv

    added a commit that references this issue on Oct 20, 2026

    Add Py_tp_token support to xxlimited module

    70d23e1

Issue actions