From 9ba2a891798a06508f63e216d3a1b6907b39eec4 Mon Sep 17 00:00:00 2001 From: Taeknology <20297177+Taeknology@users.noreply.github.com> Date: Tue, 2 Jun 2026 04:22:42 +0900 Subject: [PATCH] gh-148672: Document namespace subpackages inside regular packages (#150056) --- Doc/reference/import.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 83f0ee75e7a..4c8811560de 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.