Defining Namespace Packages for Cross-Project Module Sharing

In Python, namespace packages provide a means of structuring related code across multiple projects. To define a namespace package, it's essential to avoid placing __init__.py files within the namespace package directories.

Evolution of Namespace Packages

Before Python 3.3, namespace packages required explicit declaration using pkgutil.extend_path() or pkg_resources.declare_namespace(). However, in Python 3.3 onwards, implicit namespace packages were introduced, enabling their seamless creation without any declaration.

Interaction with Regular Packages

Namespace packages can coexist with regular packages, allowing for a hierarchical structure. When importing a module within a namespace package, Python searches within the path of the parent package, extending the search beyond the standard sys.path.

pkgutil.extend_path() vs. pkg_resources.declare_namespace()

While both pkgutil.extend_path() and pkg_resources.declare_namespace() were previously used to define namespace packages, the former is recommended for its future-proof compatibility with implicit namespace packages.

Example Structure

Consider the following directory structure:

Package-1/namespace/
Package-2/namespace/
├── path1
│  └── package
│     ├── __init__.py
│     └── foo.py
├── path2
│  └── package
│     └── bar.py
└── path3
    └── package
        ├── __init__.py
        └── baz.py

With the necessary extend_path declarations in the __init__.py files, imports such as namespace.foo, namespace.bar, and namespace.baz will all succeed.