[3.14] gh-148672: Document namespace subpackages inside regular packages (GH-150056...

gh-148672: Document namespace subpackages inside regular packages (GH-150056)
(cherry picked from commit 9ba2a891798a06508f63e216d3a1b6907b39eec4)

Co-authored-by: Taeknology <20297177+Taeknology@users.noreply.github.com>

diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index fbb901b90ecd9201598cd24d323827f4d48c506d..ead4a6964e573e7ceea2a567af6fff9a9553bbe6 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.