Creating Namespace Packages in Python for Shared Module Distribution

Introduction

In Python, namespace packages are a convenient approach for distributing related modules. They enable multiple Python products to define modules within the same namespace, thereby allowing end-users to import them seamlessly.

Implementing Namespace Packages

Implicit Namespace Packages in Python 3.3

Beginning with Python 3.3, the concept of implicit namespace packages was introduced. This eliminates the need for explicit __init__.py files within namespace package directories. The importing system automatically searches sys.path for directories without __init__.py files and initializes them as namespace packages.

Pre-Python 3.3 Solution

For Python versions prior to 3.3, the pkgutil.extend_path() method can be utilized to define explicit namespace packages:

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

This line adds any regular packages found in the search path to the path attribute of the namespace package.

Using Regular and Namespace Packages Together

In scenarios where both regular and namespace packages coexist, the extend_path() method mentioned earlier has been extended to include implicit namespace packages. This allows for the following directory structure:

├── path1
│   └── package
│       ├── __init__.py
│       └── foo.py
├── path2
│   └── package
│       └── bar.py
└── path3
    └── package
        ├── __init__.py
        └── baz.py

With __init__.py files employing extend_path(), import package.foo, import package.bar, and import package.baz will all function as expected.

pkg_resources.declare_namespace()

In contrast to pkgutil.extend_path(), the pkg_resources.declare_namespace() function has not been updated to support implicit namespace packages. Therefore, it is advisable to employ the pkgutil solution.