How to develop programs with Python Namespaced Packages?

In Python, a namespace package allows you to spread Python code among several projects. This is useful when you want to release related libraries as separate downloads while maintaining a unified import structure.

Directory Structure Example

With the directories Package-1 and Package-2 in PYTHONPATH, you can organize your code as follows ?

Package-1/
    namespace/
        __init__.py
        module1/
            __init__.py
Package-2/
    namespace/
        __init__.py
        module2/
            __init__.py

This structure allows end-users to import both namespace.module1 and namespace.module2 seamlessly.

Using Implicit Namespace Packages (Python 3.3+)

Python 3.3 introduced implicit namespace packages, which simplify the process significantly. Simply omit the __init__.py files in your namespace package directories ?

Package-1/
    namespace/
        module1/
            __init__.py
Package-2/
    namespace/
        module2/
            __init__.py

With this structure, Python automatically recognizes namespace as a namespace package.

Using pkgutil for Older Python Versions

For Python versions before 3.3, use the pkgutil module to create namespace packages. Add these lines to both Package-1/namespace/__init__.py and Package-2/namespace/__init__.py ?

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

This code extends the package's __path__ to include all subdirectories of directories on sys.path that match the package name.

Creating a Complete Example

Let's create a working example with two separate packages ?

Package-1 Structure

# Package-1/mycompany/database/__init__.py
def connect_mysql():
    return "Connected to MySQL"

Package-2 Structure

# Package-2/mycompany/utils/__init__.py
def format_data(data):
    return f"Formatted: {data}"

Using the Namespace Packages

# Both packages installed separately
from mycompany.database import connect_mysql
from mycompany.utils import format_data

# Use functions from different packages
connection = connect_mysql()
formatted = format_data("sample data")

print(connection)
print(formatted)

Connected to MySQL
Formatted: sample data

Benefits of Namespace Packages

Namespace packages provide several advantages ?

• Modular distribution: Release related functionality as separate packages
• Unified imports: Maintain consistent import paths across packages
• Team collaboration: Different teams can work on different modules independently
• Plugin architecture: Third-party developers can extend your namespace

Conclusion

Namespace packages enable distributing related Python modules across multiple packages while maintaining a unified import structure. Use implicit namespace packages for Python 3.3+ or pkgutil.extend_path() for older versions.