Skip to content

Clarify definition of native and implicit namespace packages - #1979

Merged
rgommers merged 2 commits into
pypa:mainfrom
stevepiercy:patch-1
Nov 14, 2026
Merged

rgommers merged 2 commits into
pypa:mainfrom
stevepiercy:patch-1

Conversation

@stevepiercy

@stevepiercy stevepiercy commented Dec 24, 2025 •

Copy link
Copy Markdown
Contributor

This pull request clarifies the definition of native and implicit namespace packages as synonyms, and adds a glossary term for them.

From a discussion in Discord at https://discord.com/channels/935215565872693329/935215566334079058/1451178701956976853, by an initially very confused reader who's relatively new to the terminology.

Feedback welcome. Thank you for your consideration.


📚 Documentation preview 📚: https://python-packaging-user-guide--1979.org.readthedocs.build/en/1979/

Comment thread source/glossary.rst Resolved
@ncoghlan

Copy link
Copy Markdown
Member

Something that occurred to me while reviewing the complementary PR at #1882 is that it would make sense to mutually cross link the new glossary entry with the more detailed description at
https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages

stevepiercy added a commit to stevepiercy/python-packaging-user-guide that referenced this pull request Feb 23, 2026
Add a seealso directive for native namespace packages per pypa#1979 (comment)
@stevepiercy

Copy link
Copy Markdown
Contributor Author

Something that occurred to me while reviewing the complementary PR at #1882 is that it would make sense to mutually cross link the new glossary entry with the more detailed description at https://packaging.python.org/en/latest/guides/packaging-namespace-packages/#native-namespace-packages

Done in eae76d7

@stevepiercy

Copy link
Copy Markdown
Contributor Author

Spoke too soon. I assumed there was an existing target, so I added one in bd73c03. Sorry for the noise.

There's still our little friend at:

with packages already using this method. Also, :doc:`pkg_resources <setuptools:pkg_resources>`

causing this warning:

https://github.com/pypa/packaging.python.org/actions/runs/22292222102/job/64481563875?pr=1979#step:5:66

It appears that that page no longer exists in the setuptools docs. I made a guess with a0c8b87. That appears to have resolved both issues.

@rgommers rgommers added type: enhancement A self-contained enhancement or new feature component: guides labels Nov 10, 2026

@rgommers rgommers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I merged main, resolving the merge conflict which removed the unrelated change to cross-link the setuptools docs (that sentence had been deleted in main already).

#1882 added a straightforward entry for "Namespace Package" into the glossary. What this PR adds is more detail; that should live on the full page on namespace packages, which already have a lot of detail but are missing this terminology indeed.

In my opinion, no new glossary entry for "Implicit Namespace Package" and ""Native Namespace Package" should be added, that's too niche, and duplicate with the full page. And even if we wanted that, the amount of content added for the glossary entries is way too long.

I suggest to keep the changes to packaging-namespace-packages.rst, and cross-link that from the glossary entry for "Namespace Package", possibly with a "native"/"implicit" mention.

It'd also be good to squash all commits when that is done.

@stevepiercy

Copy link
Copy Markdown
Contributor Author

I'm not altogether clear. Do you mean move the content from the glossary entry into packaging-namespace-packages.rst and merge it so it makes sense?

@rgommers

Copy link
Copy Markdown
Contributor

Yes indeed. This PR adds a .. note:: into packaging-namespace-packages.rst already; extend that a bit with some of the content that is now also added to the glossary in this PR.

Then add a link to that page from the current "Namespace Package" package, adding say one sentence to that entry. Remove the new glossary entry that's in this PR right now.

@stevepiercy

Copy link
Copy Markdown
Contributor Author

@rgommers thanks! Done in commits e5ca31f and 8312f68 through the web editor interface.

stevepiercy and others added 2 commits November 14, 2026 10:43
Explain that native and implicit namespace packages are the same PEP 420 mechanism, and describe both terms in the namespace packaging guide.

Keep the detailed terminology on the guide page rather than adding separate glossary entries.
…sentence

Point readers to the namespace packaging guide for the native and legacy
approaches, keeping the glossary definition concise.

The sentence on PEP 420 and Python 3.3 is already present in the numbered
list right above, so remove it - this also makes the added .. note::
more concise.

@rgommers rgommers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks @stevepiercy. the cross-reference from the glossary was still missing, so I added that. Also, the "PEP 420 .... Python 3.3" statement was already present right above the new .. note::, so I removed that. With that, it should be good to go now - so in it goes.

Thanks @stevepiercy, and thanks to all reviewers.

@rgommers
rgommers added this pull request to the merge queue Nov 14, 2026
Merged via the queue into pypa:main with commit 4cbef76 Nov 14, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component: guides type: enhancement A self-contained enhancement or new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants