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
• 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

[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.

[encukou]

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?

[neonene]

@encukou Could xxlimited have a m_free function or update the comment below?

cpython/Modules/xxlimited.c

Lines 436 to 437 in ac75110

	/* m_free is not necessary here: xx_clear clears all references,
	* and the module state is deallocated along with the module.

For me, xx_clear is not called if xx_modexec fails with the module not being held by heaptypes.

[encukou]

@encukou Could xxlimited have a m_free function or update the comment below?

Yes: #135174