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

[ericsnowcurrently]

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

[neonene]

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?

[ericsnowcurrently]

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.

[ericsnowcurrently]

Ideally we would update the docs back to 3.12 at least.

[encukou]

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.