Namespace packages can be understood as a way of grouping related packages, where each of these packages can be installed independently.
Namespace packages are especially useful if you have components of your application developed, packaged, and versioned independently but you still want to access them from the same namespace. This also helps to make clear to which organization or project every package belongs. For instance, for some imaginary Acme company, the common namespace could be acme. Therefore this organization could create the general acme namespace package that could serve as a container for other packages from this organization. For example, if someone from Acme wants to contribute to this namespace with, for example, an SQL-related library, they can create a new acme.sql package that registers itself in the acme namespace.
It is important to know what's the difference between normal and namespace packages and what problem they solve. Normally (without namespace packages), you would create a package called acme with an sql subpackage/submodule with the following file structure:
$ tree acme/
acme/
├── acme
│ ├── __init__.py
│ └── sql
│ └── __init__.py
└── setup.py
2 directories, 3 files
Whenever you want to add a new subpackage, let's say templating, you are forced to include it in the source tree of acme as follows:
$ tree acme/
acme/
├── acme
│ ├── __init__.py
│ ├── sql
│ │ └── __init__.py
│ └── templating
│ └── __init__.py
└── setup.py
3 directories, 4 files
Such an approach makes independent development of acme.sql and acme.templating almost impossible. The setup.py script will also have to specify all dependencies for every subpackage. So it is impossible (or at least very hard) to have an installation of some of the acme components optional. Also, with enough subpackages it is practically impossible to avoid dependency conflicts.
With namespace packages, you can store the source tree for each of these subpackages independently as follows:
$ tree acme.sql/
acme.sql/
├── acme
│ └── sql
│ └── __init__.py
└── setup.py
2 directories, 2 files
$ tree acme.templating/
acme.templating/
├── acme
│ └── templating
│ └── __init__.py
└── setup.py
2 directories, 2 files
And you can also register them independently in PyPI or any package index you use. Users can choose which of the subpackages they want to install from the acme namespace as follows, but they never install the general acme package (it doesn't even have to exist):
$ pip install acme.sql acme.templating
Note that independent source trees are not enough to create namespace packages in Python. You need a bit of additional work if you don't want your packages to not overwrite each other. Also proper handling may be different depending on the Python language version you target. Details of that are described in the next two sections.