Repository navigation
Document the unexpected importing of sub-namespaces inside normal python packages/namespaces #148672
Description
Documentation
The documentation of python import system explains that "namespaces" are meant to scatter the submodules of a same root package among several places.
It doesn't mention any change to the subpackages of a python package, which SHOULD by default include a __init__.py to be importable.
However, the attached test shows that empty folders inside a normal package or namespaces are themselves importable, thus unexpectedly creating namespaces (without any possibility to scatter files in the filesystem, when the root package itself is a normal package).
If it's a normal behaviour of the importer, shouldn't it be documented ?
Or is it actually a bug, which surprisingly makes data folders (eg. assets/ subfolders of a package) importable ?
If so, is it too late to undo that, and enforce the invariant that - except root namespaces - only folders with a __init__.py in them can be importable subpackages ?
Linked PRs
- gh-148672: Document namespace subpackages inside regular packages #150056
- [3.15] gh-148672: Document namespace subpackages inside regular packages (GH-150056) #150729
- [3.14] gh-148672: Document namespace subpackages inside regular packages (GH-150056) #150730
- [3.13] gh-148672: Document namespace subpackages inside regular packages (GH-150056) #150731
Activity
brettcannon commentedon May 8, 2026
Yes, because those are also namespace packages. There no restriction that namespace packages can only be top-level (and I don't think they are documented as such).
Sure, feel free to submit a PR if you're up for it! But I believe the docs simply don't exclude the possibility, so I think it's more of a "could" than "should".
It's too late to change by about over decade (https://peps.python.org/pep-0420/). 😉
[-]Document the unexpected importing of sub-namespaces inside normal python packages/namespaces (or treat it as bug)[/-][+]Document the unexpected importing of sub-namespaces inside normal python packages/namespaces[/+]Merge branch 'main' into pythongh-148672-document-subpackage-namespaces
gh-148672: Document namespace subpackages inside regular packages (#1…
[3.13] gh-148672: Document namespace subpackages inside regular packa…
[3.14] gh-148672: Document namespace subpackages inside regular packa…
[3.15] gh-148672: Document namespace subpackages inside regular packa…