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

AlexWaygood · 2024-09-27T20:21:49Z

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/

AlexWaygood · 2024-09-27T20:57:09Z

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

hugovk

Thank you!

Doc/reference/datamodel.rst

hugovk · 2024-09-27T21:03:15Z

Doc/reference/datamodel.rst

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


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!

Doc/reference/datamodel.rst

Co-authored-by: Hugo van Kemenade <[email protected]>

Doc/reference/datamodel.rst

Co-authored-by: Barry Warsaw <[email protected]>

Doc/reference/datamodel.rst

Co-authored-by: Barry Warsaw <[email protected]>

warsaw

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.

Doc/reference/datamodel.rst

bedevere-app · 2024-09-29T17:29:32Z

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

AlexWaygood · 2024-10-09T10:37:05Z

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!

miss-islington-app · 2024-10-09T10:54:00Z

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

miss-islington-app · 2024-10-09T11:00:04Z

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

miss-islington-app · 2024-10-09T12:16:51Z

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

miss-islington-app · 2024-10-09T12:16:51Z

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

miss-islington-app · 2024-10-09T12:16:54Z

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

miss-islington-app · 2024-10-09T12:17:10Z

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 <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

bedevere-app · 2024-10-09T18:57:03Z

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

#124709) (#125208) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

…ributes (python#124709) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]> (cherry-picked from commit 3024b16)

bedevere-app · 2024-10-09T19:05:14Z

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

#124709) (#125211) Co-authored-by: Hugo van Kemenade <[email protected]> Co-authored-by: Barry Warsaw <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]>

zware · 2024-10-10T15:36:08Z

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 bug and security fixes needs backport to 3.13 bugs and 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

Open

fixes

854de81

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

AlexWaygood requested review from willingc, ericsnowcurrently, brettcannon, ncoghlan and warsaw 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 <[email protected]>

warsaw reviewed Sep 27, 2024

View reviewed changes

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

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 <[email protected]>

warsaw reviewed Sep 27, 2024

View reviewed changes

Doc/reference/datamodel.rst Outdated Show resolved Hide resolved

Update Doc/reference/datamodel.rst

1228634

Co-authored-by: Barry Warsaw <[email protected]>

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
23 checks passed

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 bugs and security fixes and removed needs backport to 3.13 bugs and security fixes labels Oct 9, 2024

ambv added needs backport to 3.12 bug and security fixes needs backport to 3.13 bugs and security fixes and removed needs backport to 3.12 bug and security fixes needs backport to 3.13 bugs and 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 bugs and security fixes label Oct 9, 2024

bedevere-app bot removed the needs backport to 3.12 bug and security fixes label Oct 9, 2024

JelleZijlstra mentioned this pull request Oct 10, 2024

Fix linkcheck issues python/devguide#1437

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

AlexWaygood commented Sep 27, 2024 •

edited

Loading

AlexWaygood commented Sep 27, 2024 •

edited

Loading

hugovk left a comment

hugovk Sep 27, 2024

AlexWaygood Sep 27, 2024

AlexWaygood Oct 9, 2024

warsaw left a comment

bedevere-app bot commented Sep 29, 2024

AlexWaygood commented Oct 9, 2024 •

edited

Loading

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

zware commented Oct 10, 2024

gh-101100: Consolidate documentation on ModuleType attributes #124709

gh-101100: Consolidate documentation on ModuleType attributes #124709

Conversation

AlexWaygood commented Sep 27, 2024 • edited Loading

AlexWaygood commented Sep 27, 2024 • edited Loading

hugovk left a comment

Choose a reason for hiding this comment

hugovk Sep 27, 2024

Choose a reason for hiding this comment

AlexWaygood Sep 27, 2024

Choose a reason for hiding this comment

AlexWaygood Oct 9, 2024

Choose a reason for hiding this comment

warsaw left a comment

Choose a reason for hiding this comment

bedevere-app bot commented Sep 29, 2024

AlexWaygood commented Oct 9, 2024 • edited Loading

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

miss-islington-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

bedevere-app bot commented Oct 9, 2024

zware commented Oct 10, 2024

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

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

AlexWaygood commented Sep 27, 2024 •

edited

Loading

AlexWaygood commented Sep 27, 2024 •

edited

Loading

AlexWaygood commented Oct 9, 2024 •

edited

Loading