From 74e65289f2da60b6bb69d2622234c9992a05da58 Mon Sep 17 00:00:00 2001 From: Taeknology <20297177+Taeknology@users.noreply.github.com> Date: Tue, 19 May 2026 14:08:58 +0900 Subject: [PATCH] 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. --- Doc/reference/import.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 83f0ee75e7aebd..4c8811560de2e3 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.