The following examples demonstrates the usage / installation of pkgutil style namespace packages.

pkgutil/
├ pkg_a/               # the name of this dir doesn't matter
│  ├ setup.py
│  └ example_pkg/      # namespace package name
│      ├__init__.py    # special pkgutil namespace __init__.py
│      └ a/            # dir name must match the package name from `setup.py`
│        └ __init__.py
│        ├ module1.py
.
.
.
└ pkg_b/

The anatomy of a namespace package name is <namespaceA>.<package_name>. Namespaces can also be nested an take the form <namespaceA>.<namespace_N>.<package_name>.

This subdirectory contains two packages ("a" & "b") that share the namespace example_pkg. When installed these packages will have the names example_pkg.a & example_pkg.b respectively.

The directories pkg_a and pkg_b in this subdirectory contain two different python packages. The names of these directories have no effect on the installed package.

Each of these directories should at least contain:

1. A configuration file, in this case setup.py.
2. A directory, whose name determines the namespace name.

In this example example_pkg is the name of the namespace. This directory should contain:

1. The __init__.py file for the namespace package, which must contain only the following:

   __path__ = __import__('pkgutil').extend_path(__path__, __name__)

   Nested namespaces must contain an identical __init__.py.

2. A directory, whose name determines the package_name. This directory holds the package's source code.

   • The directory name, must match the name given in the setup.py.

When using namespace packages, it is helpful to understand that the delimiter between the namespace and the package_name is not consistent throughout common python workflows.

For example, here is how to reference the namespace package "a" from this repository.

• Creating your namespace package with setuptools in setup.py:
  • setup(name="example_pkg_a")
• Installing / Uninstalling a namespace package with pip:
  • pip install example-pkg-a
• Importing a namespace package withpython:
  • import example_pkg.a

From the root directory, running the following command will install a package called example_pkg.a.

cd pkgutil/pkg_a

python -m pip install .

# Test the install by printing the `name` from the `__init__.py` file.
python -c "import example_pkg.a as a; print(a.name)"