Skip to content

Commit 74e6528

Browse files
committed
gh-148672: Document namespace subpackages inside regular packages
The import system already creates implicit namespace packages for any subdirectory of a regular package that lacks an ``__init__.py`` file, per :pep:`420`. Document this behaviour in Doc/reference/import.rst so readers do not have to infer it from the PEP and from importlib internals.
1 parent 68ebc05 commit 74e6528

1 file changed

Lines changed: 12 additions & 0 deletions

File tree

Doc/reference/import.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,12 @@ Importing ``parent.one`` will implicitly execute ``parent/__init__.py`` and
122122
``parent.three`` will execute ``parent/two/__init__.py`` and
123123
``parent/three/__init__.py`` respectively.
124124

125+
A subdirectory inside a regular package that does not contain an
126+
``__init__.py`` file is treated as an implicit
127+
:ref:`namespace package <reference-namespace-package>` (a "namespace
128+
subpackage") rooted in that parent. See :pep:`420` for the underlying
129+
specification.
130+
125131

126132
.. _reference-namespace-package:
127133

@@ -153,6 +159,12 @@ physically located next to ``parent/two``. In this case, Python will create a
153159
namespace package for the top-level ``parent`` package whenever it or one of
154160
its subpackages is imported.
155161

162+
Namespace packages may also be nested inside a regular package. When the
163+
import system searches a regular package's ``__path__`` and encounters a
164+
subdirectory that does not contain an ``__init__.py`` file, that
165+
subdirectory becomes a :term:`portion` contributing to a namespace
166+
subpackage of the enclosing regular package.
167+
156168
See also :pep:`420` for the namespace package specification.
157169

158170

0 commit comments

Comments
 (0)