Find file History
r-kells and theacodes Pkgutil detailed readme (#10)
* create detailed readme

* grammar
Latest commit 39754bd Nov 5, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
pkg_a Update all's to zip_safe=False. Nov 1, 2017
pkg_b Update all's to zip_safe=False. Nov 1, 2017 Pkgutil detailed readme (#10) Nov 5, 2018

pkgutil-style namespace packages

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

├ pkg_a/               # the name of this dir doesn't matter
│  ├
│  └ example_pkg/      # namespace package name
│      ├    # special pkgutil namespace
│      └ a/            # dir name must match the package name from ``
│        └
│        ├
└ 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.a respectively.

Detailed Requirements

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:

  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 file for the namespace package, which must contain only the following:

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

    Nested namespaces must contain an identical

  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

Practical Usage

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(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

pip install .

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