Document the unexpected importing of sub-namespaces inside normal python packages/namespaces

[pakal]

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 ?

PythonNamespaceTests.zip

Linked PRs

• gh-148672: Document namespace subpackages inside regular packages #150056

[brettcannon]

However, the attached test shows that empty folders inside a normal package or namespaces are themselves importable

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

If it's a normal behaviour of the importer, shouldn't it be documented ?

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

is it too late to undo that

It's too late to change by about over decade (https://peps.python.org/pep-0420/). 😉