Skip to content
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 our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify import vs. distribution packages in Using importlib_metadata docs #399

Merged

Conversation

CAM-Gerlach
Copy link
Member

As requested on the Python Discourse, addresses #398 (import vs. distribution packages not being clear) by:

  • Using "distribution package"/"import package" on first use in each section
  • Disambiguating the unqualified term "package" (preferring "distribution" and "import package", respectively) 1
  • Linking the terms to the PyPA glossary once on first use in each section they are used in 2
  • Adding an admonition at the top explicitly calling out the differences and referring the reader to the package_distributions() function to map between them

Additionally, this incorporates a couple required/directly related changes:

  • Fix a few grammar/textual problems on already-modified lines
  • Add an intersphinx mapping to packaging.python.org to properly reference the terms and specs there 3
  • Also uses such to reference the canonical, self-contained, up to date Core metadata spec rather than an old, incremental, historical PEP. 4

Fix #398

Reviewer notes:

Footnotes

  1. I'm not 100% sure myself about the disambiguations in the highly technical Extending the search algorithm Explanation—please check to confirm I've gotten them correct.

  2. If this needs to go in your skeleton, I can submit a PR there, drop that commit here and rebase accordingly once that is updated. Also, I was confused by some were written as dict literals, and some were added with dict.update, with no obvious or stated reason—I though it might have to do with the former being from your skeleton and the latter being local, but your skeleton looks identical, so I'm not sure what's going on or where packaging.python.org. Please advise and I'll be happy to add it in whichever manner is appropriate.

  3. If required, I can pull this out to a separate followup PR, though it is small enough I just added it here to avoid extra overhead on both our parts.

Copy link
Member

@jaraco jaraco left a comment

Choose a reason for hiding this comment

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

Looks good to me. Just one question.

docs/using.rst Outdated Show resolved Hide resolved
@jaraco jaraco merged commit 165d7b7 into python:main Oct 1, 2022
@CAM-Gerlach
Copy link
Member Author

Hey @jaraco sorry for missing this and thanks for taking care of it; I was extremely busy for the Artemis 1 launch attempts during this time and then must have accidentally dismissed it (I believe I mistakenly thought it was a different unrelated issue rather than this PR). You shouldn't have to, but in the future you're welcome to give me a ping on Discord, etc. just in case I miss something like this in the future, so you don't have to wait around for a month and then have to do it yourself. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Docs do not always clearly distinguish between import vs distribution packages
2 participants