Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

gh-101100: Consolidate documentation onModuleType attributes#124709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
AlexWaygood merged 16 commits intopython:mainfromAlexWaygood:moduletype-attrs
Oct 9, 2024

Conversation

AlexWaygood
Copy link
Member

@AlexWaygoodAlexWaygood commentedSep 27, 2024•
edited
Loading

Our documentation forModuleType 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 fortypes.ModuleType; and some in the API entry forimportlib.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 forattributes on class objects,attributes on function objects, andattributes 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.

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

@AlexWaygood
Copy link
MemberAuthor

AlexWaygood commentedSep 27, 2024•
edited
Loading

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

Copy link
Member

@hugovkhugovk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Thank you!

AlexWaygood reacted with heart emoji
Comment on lines 1017 to 1021
.. 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Should this use adeprecated-removed?

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

Copy link
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Should this use adeprecated-removed?

I think that makes sense!

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

It doesn't appear so. This note is mostly copied from the note that currently exists athttps://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'mkinda 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.

Copy link
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I took a stab at improving this a bit in309a9cf and2dca569!

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Barry Warsaw <barry@python.org>
Copy link
Member

@warsawwarsaw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

AlexWaygood reacted with thumbs up emoji
@bedevere-app
Copy link

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

@AlexWaygood
Copy link
MemberAuthor

AlexWaygood commentedOct 9, 2024•
edited
Loading

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 thantyping.__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 probablycan't be removed in 3.14 at this stage, personally... but you'll have to convince@hugovk, not me 😉)

  • Theglossary definition of "loader" states:

    It must define a method named load_module().

    Which seems incorrect ifload_module is going away!

@AlexWaygoodAlexWaygoodenabled auto-merge (squash)October 9, 2024 10:43
@AlexWaygoodAlexWaygood merged commit3024b16 intopython:mainOct 9, 2024
23 checks passed
@AlexWaygoodAlexWaygood deleted the moduletype-attrs branchOctober 9, 2024 10:53
@miss-islington-app
Copy link

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

@AlexWaygoodAlexWaygood added needs backport to 3.13bugs and security fixes and removed needs backport to 3.13bugs and security fixes labelsOct 9, 2024
@miss-islington-app
Copy link

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

@ambvambv added needs backport to 3.12only security fixes needs backport to 3.13bugs and security fixes and removed needs backport to 3.12only security fixes needs backport to 3.13bugs and security fixes labelsOct 9, 2024
@miss-islington-app
Copy link

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

@miss-islington-app
Copy link

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

@miss-islington-app
Copy link

Sorry,@AlexWaygood, I could not cleanly backport this to3.12 due to a conflict.
Please backport usingcherry_picker on command line.

cherry_picker 3024b16d51bb7f74177c5a5038cc9a56fd2b26bd 3.12
AlexWaygood reacted with hooray emoji

@miss-islington-app
Copy link

Sorry,@AlexWaygood, I could not cleanly backport this to3.13 due to a conflict.
Please backport usingcherry_picker on command line.

cherry_picker 3024b16d51bb7f74177c5a5038cc9a56fd2b26bd 3.13
AlexWaygood reacted with hooray emoji

AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull requestOct 9, 2024
…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>
@bedevere-app
Copy link

GH-125208 is a backport of this pull request to the3.13 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.13bugs and security fixes labelOct 9, 2024
AlexWaygood added a commit that referenced this pull requestOct 9, 2024
#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>
AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull requestOct 9, 2024
…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 commit3024b16)
@bedevere-app
Copy link

GH-125211 is a backport of this pull request to the3.12 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.12only security fixes labelOct 9, 2024
AlexWaygood added a commit that referenced this pull requestOct 9, 2024
#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>
@zware
Copy link
Member

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

AlexWaygood reacted with thumbs up emoji

Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@JelleZijlstraJelleZijlstraJelleZijlstra left review comments

@hugovkhugovkhugovk approved these changes

@warsawwarsawwarsaw approved these changes

@willingcwillingcAwaiting requested review from willingcwillingc is a code owner

@ericsnowcurrentlyericsnowcurrentlyAwaiting requested review from ericsnowcurrentlyericsnowcurrently is a code owner

@brettcannonbrettcannonAwaiting requested review from brettcannonbrettcannon is a code owner

@ncoghlanncoghlanAwaiting requested review from ncoghlanncoghlan is a code owner

Assignees

@AlexWaygoodAlexWaygood

Labels
docsDocumentation in the Doc dirtopic-importlib
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

6 participants
@AlexWaygood@zware@warsaw@JelleZijlstra@hugovk@ambv
[8]ページ先頭
©2009-2025 Movatter.jp