From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 1 Jun 2026 19:30:29 +0000 (+0200)
Subject: [3.14] gh-148672: Document namespace subpackages inside regular packages (GH-150056... 
X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=a082d4798f9309faae664e8ea5b058a104731af8;p=thirdparty%2FPython%2Fcpython.git

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

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 fbb901b90ecd..ead4a6964e57 100644
--- 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.