Skip to content

Commit 5215bae

Browse files
committed
Doc: update term "namespace package"
Recommend using regular package officially to avoid people just think `__init__.py` is not necessary.
1 parent 732670d commit 5215bae

File tree

2 files changed

+10
-2
lines changed

2 files changed

+10
-2
lines changed

Doc/glossary.rst

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -936,11 +936,17 @@ Glossary
936936
modules, respectively.
937937

938938
namespace package
939-
A :pep:`420` :term:`package` which serves only as a container for
940-
subpackages. Namespace packages may have no physical representation,
939+
A :term:`package` which serves only as a container for subpackages.
940+
Namespace packages may have no physical representation,
941941
and specifically are not like a :term:`regular package` because they
942942
have no ``__init__.py`` file.
943943

944+
Namespace packages allow you to split single package across multiple directories or distributions.
945+
On the other hand, namespace packages have some drawbacks and pitfalls.
946+
Use :term:`regular package` always when it fits your needs.
947+
948+
For more information, see :pep:`420` and :ref:`reference-namespace-package`.
949+
944950
See also :term:`module`.
945951

946952
nested scope

Doc/reference/import.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,8 @@ Importing ``parent.one`` will implicitly execute ``parent/__init__.py`` and
123123
``parent/three/__init__.py`` respectively.
124124

125125

126+
.. _reference-namespace-package:
127+
126128
Namespace packages
127129
------------------
128130

0 commit comments

Comments
 (0)