GH-134160: Prefer multi-phase initialisation in docs #134764
Conversation
AA-Turner
added
docs
| An alternate way to specify extensions is to request "multi-phase initialization". | ||
| The preferred method to specify extensions is to request "multi-phase initialization". | ||
| Extension modules created this way behave more like Python modules: the | ||
| initialization is split between the *creation phase*, when the module object | ||
| is created, and the *execution phase*, when it is populated. | ||
| The distinction is similar to the :py:meth:`!__new__` and :py:meth:`!__init__` methods | ||
| of classes. | ||
|
|
||
| Unlike modules created using single-phase initialization, these modules are not | ||
| singletons: if the *sys.modules* entry is removed and the module is re-imported, | ||
| a new module object is created, and the old module is subject to normal garbage | ||
| collection -- as with Python modules. | ||
| Unlike modules created using the legacy single-phase initialization mechanism, | ||
| these modules are not singletons: if the *sys.modules* entry is removed and | ||
| the module is re-imported, a new module object is created, and the old module | ||
| is subject to normal garbage collection -- as with Python modules. |
There was a problem hiding this comment.
I think this shouldn't be a comparison. If we're calling single-phase “legacy” (which finally seems to be the cunsensus), then this section should describe what modules are, and the single-phase section should describe the eldritch weirdness of that method.
Should I try to reword it that way? (I'd like to avoid merge conflicts.)
There was a problem hiding this comment.
There is existing mention of single-phase as 'legacy', though admittedly in a niche location: https://docs.python.org/3/c-api/init.html#c.PyInterpreterConfig.check_multi_interp_extensions
There was a problem hiding this comment.
Should I try to reword it that way? (I'd like to avoid merge conflicts.)
@encukou feel free to push to this branch.
Follows from #134296.
A
📚 Documentation preview 📚: https://cpython-previews--134764.org.readthedocs.build/