gh-101100: Consolidate documentation on `ModuleType` attributes by AlexWaygood · Pull Request #124709 · python/cpython · GitHub

Our documentation for ModuleType attributes is currently quite scattered. Some attributes are documented in the data model; some in the reference guide for the import system; some in the API entry for types.ModuleType; and some in the API entry for importlib.abc.Loader.load_module. Some attributes are documented in several of these places, but the different entries say different things about the same attribute!

This PR consolidates documentation for these attributes into a single list of attributes in the datamodel docs. This is a similar approach to the one we use for attributes on class objects, attributes on function objects, and attributes on code objects. (Unlike those links, though, I haven't used a table for all module attributes, since some of the import-system-related attributes are described over the course of several paragraphs!)

I've tried to keep this PR as small as possible. Unfortunately, in order to not break existing cross references in the documentation, a number of other files have had to be updated as part of the same PR.

Issue: Fix all Sphinx reference warnings in the documentation #101100

📚 Documentation preview 📚: https://cpython-previews--124709.org.readthedocs.build/

Docs preview for the new sections in the datamodel describing module attributes: https://cpython-previews--124709.org.readthedocs.build/en/124709/reference/datamodel.html#modules

Thank you!

Should this use a deprecated-removed?

Is it documented in What's New and deprecations/pending-removal-in-3.14.rst?

Should this use a deprecated-removed?

I think that makes sense!

Is it documented in What's New and deprecations/pending-removal-in-3.14.rst?

It doesn't appear so. This note is mostly copied from the note that currently exists at https://docs.python.org/3/reference/import.html#loader__, but with some more cross-reference links added.

I'll change the directive to be .. deprecated-removed, but I'm kinda tempted to say that adding a note to "What's new" is out of scope for this PR, which essentially moves documentation around and consolidates it rather than adding new documentation.

I took a stab at improving this a bit in 309a9cf and 2dca569!

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Co-authored-by: Barry Warsaw <barry@python.org>

I'm not quite finished reviewing this, but because my laptop got rebooted, I'm hoping GH preserved my previous comments. I'll complete the review hopefully tomorrow.

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

Thanks all for the excellent review comments! I'm going to land this now -- there's definitely still room for improvement, but I think it can all be done in followups.

A summary of things that could still be clarified:

Are __path__ and/or __file__ deprecated? There's no deprecation warning in the docs currently for either of these, so this PR doesn't add one for either. If they're not deprecated, maybe we could consider splitting the docs for these attributes into a different section (along with __name__), so that it's clear that it's still okay for users to read them and rely on them?
For the attributes that are definitely not deprecated, such as __name__, do we still want to recommend users to read them from the __spec__ attribute where possible? Asking users to do that from within the module globals (e.g. if __spec__.name == "__main__") feels a bit implausible, but it's maybe not unreasonable to ask users to access it from __spec__ when they're accessing it on an imported module (typing.__spec__.name rather than typing.__name__). It would still cause a lot of churn to a lot of currently working code, though!
importlib.abc.Loader.load_module is deprecated, but doesn't indicate when it will be removed. (I'd argue this means it probably can't be removed in 3.14 at this stage, personally... but you'll have to convince @hugovk, not me 😉)
The glossary definition of "loader" states:

It must define a method named load_module().

Which seems incorrect if load_module is going away!

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

Sorry, @AlexWaygood, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 3024b16d51bb7f74177c5a5038cc9a56fd2b26bd 3.12

Sorry, @AlexWaygood, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 3024b16d51bb7f74177c5a5038cc9a56fd2b26bd 3.13

…tributes (python#124709) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Barry Warsaw <barry@python.org> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

GH-125208 is a backport of this pull request to the 3.13 branch.

#124709) (#125208) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Barry Warsaw <barry@python.org> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

…ributes (python#124709) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Barry Warsaw <barry@python.org> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> (cherry-picked from commit 3024b16)

GH-125211 is a backport of this pull request to the 3.12 branch.

#124709) (#125211) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Barry Warsaw <barry@python.org> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Note: this caused some reference warnings in the devguide via intersphinx by removing the .. attribute:: __file__ section; see this CI run for python/devguide@97ad694 (python/devguide#1434). Not sure it's worth changing here, just connecting the dots :)

Consolidate documentation on ModuleType attributes

6dabc1b

AlexWaygood added topic-importlib needs backport to 3.12 only security fixes needs backport to 3.13 only security fixes labels Sep 27, 2024

AlexWaygood requested review from JelleZijlstra and hugovk September 27, 2024 20:21

bedevere-app Bot added the docs Documentation in the Doc dir label Sep 27, 2024

bedevere-app Bot mentioned this pull request Sep 27, 2024

Fix all Sphinx reference warnings in the documentation #101100

Closed

fixes

854de81

AlexWaygood marked this pull request as ready for review September 27, 2024 20:41

AlexWaygood requested review from brettcannon, ericsnowcurrently, ncoghlan, warsaw and willingc as code owners September 27, 2024 20:41

bedevere-app Bot added the awaiting core review label Sep 27, 2024

hugovk approved these changes Sep 27, 2024

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Sep 27, 2024

Apply suggestions from code review

997895d

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

warsaw reviewed Sep 27, 2024

View reviewed changes

Comment thread Doc/reference/datamodel.rst Outdated

AlexWaygood and others added 2 commits September 27, 2024 14:31

change directive to .. deprecated-removed

d23c6be

Update Doc/reference/datamodel.rst

404d5a9

Co-authored-by: Barry Warsaw <barry@python.org>

warsaw reviewed Sep 27, 2024

View reviewed changes

Comment thread Doc/reference/datamodel.rst Outdated

Update Doc/reference/datamodel.rst

1228634

Co-authored-by: Barry Warsaw <barry@python.org>

warsaw requested changes Sep 29, 2024

View reviewed changes

bedevere-app Bot added awaiting changes and removed awaiting merge labels Sep 29, 2024

AlexWaygood added 2 commits October 9, 2024 11:16

fix build

7716393

even more deprecation notes

d68fb58

AlexWaygood enabled auto-merge (squash) October 9, 2024 10:43

AlexWaygood merged commit 3024b16 into python:main Oct 9, 2024

AlexWaygood deleted the moduletype-attrs branch October 9, 2024 10:53

bedevere-app Bot removed the awaiting merge label Oct 9, 2024

AlexWaygood added needs backport to 3.13 only security fixes and removed needs backport to 3.13 only security fixes labels Oct 9, 2024

ambv added needs backport to 3.12 only security fixes needs backport to 3.13 only security fixes and removed needs backport to 3.12 only security fixes needs backport to 3.13 only security fixes labels Oct 9, 2024

miss-islington-app Bot assigned AlexWaygood Oct 9, 2024

bedevere-app Bot removed the needs backport to 3.13 only security fixes label Oct 9, 2024

bedevere-app Bot removed the needs backport to 3.12 only security fixes label Oct 9, 2024

JelleZijlstra mentioned this pull request Oct 10, 2024

Fix linkcheck issues python/devguide#1437

Merged

+                 .. versionchanged:: 3.12
+                    The value of :attr:`!module__loader__` is expected to be the same as
+                    :attr:`__spec__.loader <importlib.machinery.ModuleSpec.loader>`.
+                    The use of :attr:`!module.__loader__` is deprecated and slated for
+                    removal in Python 3.14.

gh-101100: Consolidate documentation on `ModuleType` attributes by AlexWaygood · Pull Request #124709 · python/cpython · GitHub

Repository navigation

gh-101100: Consolidate documentation on ModuleType attributes - #124709

gh-101100: Consolidate documentation on ModuleType attributes#124709AlexWaygood merged 16 commits intopython:mainpython/cpython:mainfrom AlexWaygood:moduletype-attrsAlexWaygood/cpython:moduletype-attrsCopy head branch name to clipboard

Conversation

AlexWaygood commented Sep 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AlexWaygood commented Sep 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

hugovk Sep 27, 2024

Choose a reason for hiding this comment

Uh oh!

AlexWaygood Sep 27, 2024

Choose a reason for hiding this comment

Uh oh!

AlexWaygood Oct 9, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

warsaw left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-app Bot commented Sep 29, 2024

Uh oh!

AlexWaygood commented Oct 9, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miss-islington-app Bot commented Oct 9, 2024

Uh oh!

miss-islington-app Bot commented Oct 9, 2024

Uh oh!

miss-islington-app Bot commented Oct 9, 2024

Uh oh!

miss-islington-app Bot commented Oct 9, 2024

Uh oh!

miss-islington-app Bot commented Oct 9, 2024

Uh oh!

miss-islington-app Bot commented Oct 9, 2024

Uh oh!

bedevere-app Bot commented Oct 9, 2024

Uh oh!

bedevere-app Bot commented Oct 9, 2024

Uh oh!

zware commented Oct 10, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

gh-101100: Consolidate documentation on ModuleType attributes#124709
AlexWaygood merged 16 commits into
python:mainfrom
AlexWaygood:moduletype-attrs

AlexWaygood commented Sep 27, 2024 •
edited
Loading

AlexWaygood commented Sep 27, 2024 •
edited
Loading

AlexWaygood commented Oct 9, 2024 •
edited
Loading