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

diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index 83f0ee75e7aebd33312a4e3bbaa434fa39ddbe7e..4c8811560de2e3f6eaf287a871db5f60f5eb8f88 100644 (file)
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -122,6 +122,12 @@ Importing ``parent.one`` will implicitly execute ``parent/__init__.py`` and
 ``parent.three`` will execute ``parent/two/__init__.py`` and
 ``parent/three/__init__.py`` respectively.
 
+A subdirectory inside a regular package that does not contain an
+``__init__.py`` file is treated as an implicit
+:ref:`namespace package <reference-namespace-package>` (a "namespace
+subpackage") rooted in that parent.  See :pep:`420` for the underlying
+specification.
+
 
 .. _reference-namespace-package:
 
@@ -153,6 +159,12 @@ physically located next to ``parent/two``.  In this case, Python will create a
 namespace package for the top-level ``parent`` package whenever it or one of
 its subpackages is imported.
 
+Namespace packages may also be nested inside a regular package.  When the
+import system searches a regular package's ``__path__`` and encounters a
+subdirectory that does not contain an ``__init__.py`` file, that
+subdirectory becomes a :term:`portion` contributing to a namespace
+subpackage of the enclosing regular package.
+
 See also :pep:`420` for the namespace package specification.