From 5215baeb42130bfa51a40dcb1fece692829daf85 Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Fri, 24 Jan 2025 14:40:02 +0900 Subject: [PATCH 1/4] Doc: update term "namespace package" Recommend using regular package officially to avoid people just think `__init__.py` is not necessary. --- Doc/glossary.rst | 10 ++++++++-- Doc/reference/import.rst | 2 ++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index e3a14601398e89..dbce0f57445c9a 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -936,11 +936,17 @@ 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 you to split single package across multiple directories or distributions. + On the other hand, namespace packages have some drawbacks and pitfalls. + Use :term:`regular package` always when it fits your needs. + + 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 ac363e8cfa00dc..26a8b2d9c7187e 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 ------------------ From 16d5407b3d597370e9bd381080f854ecd97021ae Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Fri, 24 Jan 2025 17:49:07 +0900 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index dbce0f57445c9a..395c15550991c1 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -941,8 +941,8 @@ Glossary and specifically are not like a :term:`regular package` because they have no ``__init__.py`` file. - Namespace packages allow you to split single package across multiple directories or distributions. - On the other hand, namespace packages have some drawbacks and pitfalls. + Namespace packages allow you to split a single package across multiple directories or distributions. + On the other hand, namespace packages have several drawbacks and pitfalls. Use :term:`regular package` always when it fits your needs. For more information, see :pep:`420` and :ref:`reference-namespace-package`. From 64f6e7335358c2fc4758b49a43d885883b9708bc Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Sat, 25 Jan 2025 17:05:43 +0900 Subject: [PATCH 3/4] Update Doc/glossary.rst --- Doc/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 395c15550991c1..1ecd09c75c95b0 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -941,7 +941,7 @@ Glossary and specifically are not like a :term:`regular package` because they have no ``__init__.py`` file. - Namespace packages allow you to split a single package across multiple directories or distributions. + Namespace packages allow several individually installable packages to have a common parent package. On the other hand, namespace packages have several drawbacks and pitfalls. Use :term:`regular package` always when it fits your needs. From c33cc85ff49a0c29bfccd7a1d554698d7cb6d610 Mon Sep 17 00:00:00 2001 From: Inada Naoki Date: Fri, 14 Feb 2025 14:16:18 +0900 Subject: [PATCH 4/4] simplify --- Doc/glossary.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 1ecd09c75c95b0..a1ed2e8e4213fc 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -942,8 +942,7 @@ Glossary have no ``__init__.py`` file. Namespace packages allow several individually installable packages to have a common parent package. - On the other hand, namespace packages have several drawbacks and pitfalls. - Use :term:`regular package` always when it fits your needs. + Otherwise, it is recommended to use a :term:`regular package`. For more information, see :pep:`420` and :ref:`reference-namespace-package`.