Documentation build overview

📚 cpython-previews | 🛠️ Build #35229670 | 📁 Comparing fa6ddd4 against main (2cd6d4b)

  🔍 Preview build  

+ Added

• builtins/constants.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/index.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• builtins/time-complexity.html
• library/tkinter.dialogs.html

± Modified

• glossary.html
• index.html
• license.html
• _static/tachyon-example-heatmap.html
• c-api/bytearray.html
• c-api/bytes.html
• c-api/capsule.html
• c-api/complex.html
• c-api/exceptions.html
• c-api/extension-modules.html
• and 135 more...

Could you turn “legacy single-phase initialization” into a link? (And remove the parenthesis -- PyModule_Create is just an example.)

Also, please link the “as is done for”/“as for” parts -- the docs for the mentioned feature should explain what happens in more detail; if they don't then the mention isn't very useful.

The existing docs already point out that the init function is not called twice. It would be nice to clarify there what the “lookup key“ is when determining subsequent imports of the “same” module.

Done, thanks for the suggestions @encukou !

I'll rebase, and reword a bit.

@itamaro, how's this look?

@itamaro, how's this look?

Thanks @encukou , this reads much better than what I had! the merge looks good too.

should we make the collision case more accurate? in two places (extension-modules.rst from my commits and import.rst in your commit) we're explaining how initfunc is not called again on name collision, but this is technically correct only for builtins and inittab extensions (and modules created through PyImport_CreateModuleFromInitfunc) - those can't collide with .so-file-based extensions (the path is part of the cache key).

possible changes:

• If a single-phase module was previously created under the same name by this function or as a built-in module (e.g. one registered with PyImport_AppendInittab), including in another interpreter, Python does not call initfunc again...

and for extension-modules.rst: "Modules are matched to the saved contents by the module's full dotted name (and, for extensions loaded from a file, the file's path)".

another nit: "reuses the previous module's contents" is only accurate for m_size == -1. For m_size >= 0, the behavior depends on which interpreter loaded the module first (it may re-run the first cached init function, or call the new one). not sure how deeply we want to document that. maybe a short "for modules with m_size of -1" qualifier, or just rely on the "implementation detail" framing. wdyt?

happy to push the changes if you'd like.

Hm, right. I guess it makes sense to document this, especially since it's soft-deprecated and thus should not change.
We get a wall of text full of weird edge cases; rather than “how to use this” it tells you “why you shouldn't use single-phase init”.

I still left out the subinterpreter-specific behaviour, saying it could go either way.

Does this look good?

Please feel free to push directly, it's your PR :)

thanks @encukou, I merged main and pushed a couple of tiny nits, let me know if you have any final feedback before merging! (or just approve if it looks good to you :) )

Thanks @itamaro for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

GH-159791 is a backport of this pull request to the 3.15 branch.