From a082d4798f9309faae664e8ea5b058a104731af8 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 1 Jun 2026 21:30:29 +0200 Subject: [PATCH] [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> --- Doc/reference/import.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) 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 ` (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. -- 2.47.3