From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 15 Feb 2025 06:11:38 +0000 (+0100)
Subject: Doc: update term "namespace package" (GH-129251)
X-Git-Tag: v3.12.10~214
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=de1279a0169d98ff17ef83d6cc6bfb74c9cee91f;p=thirdparty%2FPython%2Fcpython.git

Doc: update term "namespace package" (GH-129251)

(cherry picked from commit e65e9f90626a4c62da4d3500044f354b51e51dbb)
Co-authored-by: Inada Naoki <songofacandy@gmail.com>
---

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index be8201ef4194..f57f00b0ae13 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -873,11 +873,16 @@ Glossary
       modules, respectively.
 
    namespace package
-      A :pep:`420` :term:`package` which serves only as a container for
-      subpackages.  Namespace packages may have no physical representation,
+      A :term:`package` which serves only as a container for subpackages.
+      Namespace packages may have no physical representation,
       and specifically are not like a :term:`regular package` because they
       have no ``__init__.py`` file.
 
+      Namespace packages allow several individually installable packages to have a common parent package.
+      Otherwise, it is recommended to use a :term:`regular package`.
+
+      For more information, see :pep:`420` and :ref:`reference-namespace-package`.
+
       See also :term:`module`.
 
    nested scope
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index ac363e8cfa00..26a8b2d9c718 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -123,6 +123,8 @@ Importing ``parent.one`` will implicitly execute ``parent/__init__.py`` and
 ``parent/three/__init__.py`` respectively.
 
 
+.. _reference-namespace-package:
+
 Namespace packages
 ------------------