What's a Python Namespace Package, and What's It For?

In Short: Python Namespace Packages Are a Way to Organize Multiple Packages

By way of a quick recap, you’ll first examine the general concept of a Python namespace before tackling namespace packages. A namespace is a way to group objects under a specific name. You can group values, functions, and other objects.

For example, when you import math, you gain access to the math namespace. Inside the math namespace, you can select from a whole host of different objects.

You can also think of a Python dictionary as a namespace. With a Python dictionary, you can take two variables that started out as completely separate, independent variables and include them within the same dictionary namespace:

>>> real_python = {}

>>> home_page = "https://realpython.com"
>>> import_tutorial = "python-import"

>>> real_python["home_page"] = home_page
>>> real_python["import_tutorial"] = import_tutorial

Now, you can reference both the home_page and import_tutorial values from the real_python namespace. Namespace packages work in a similar way, but they combine whole packages instead of values or other Python objects.

This allows you to have two independent packages on PyPI, for example, that still share the same namespace. One single namespace package doesn’t make a whole lot of sense. To really see the advantage of namespace packages, you need at least two packages.

Namespace packages are typically used by businesses that may have extensive libraries of packages that they want to keep under a company namespace. For example, the Microsoft Azure packages are all accessible, once installed, through the azure namespace.

That’s why you’ll create your own company namespace in the next section.

What Does a Namespace Package Look Like?

Imagine you work for the Snake Corporation, and your team wants to make sure that all the packages in its library are always accessible from the snake_corp namespace. So, no matter what package you’re using, as long as it was made by the Snake Corporation, you’ll import from snake_corp.

Without namespace packages, you’d have two options:

1. Create a monorepo, which would be a single package called snake_corp with hundreds of modules for all the different libraries and utilities that you might need.
2. Create various packages, but prefix them all with snake_corp. For example, you might have snake_corp_dateutil as a package.

The trouble with creating a monorepo is that everyone has to download all the code even if they only use a tiny fraction of it. It also complicates matters in terms of version management and other packaging workflows, especially if different teams are in charge of different subpackages.

The issue with creating various packages with a common prefix is that it can be quite verbose, messy, and inelegant. And, at the end of the day, the Snake Corporation CEO has said that they don’t like that solution. They’d prefer using a monorepo over prefixing all the packages. Besides, using common prefixes is just a convention that doesn’t technically create a common namespace.

What you have in this situation is a perfect use case for namespace packages! Namespace packages allow you to have multiple separate packages with their own packaging workflow, but they can all live in the same snake_corp namespace.

To illustrate how you can achieve the kind of structure to make the Snake Corporation CEO happy, you’ll now make three packages:

1. snake-corp-dateutil: Some date utilities specific to the Snake Corporation
2. snake-corp-magic-numbers: Some number-generation utilities specific to the Snake Corporation
3. snake-service: An employee project that wants to make use of both the snake-corp-dateutil and snake-corp-magic-numbers packages

In this example, you’ll take the prose name to be the same as the pip name.

In the next section, you’ll set up the packages and install them in your virtual environment. In the section after that, you’ll get to use them.

snake-corp/
│
├── snake-corp-dateutil/
│   ├── snake_corp/
│   │   └── dateutil.py
│   └── pyproject.toml
│
├── snake-corp-magic-numbers/
│   ├── snake_corp/
│   │   └── magic.py
│   └── pyproject.toml
│
└── snake-service/
    └── snake_service.py

# snake-corp-dateutil/snake_corp/dateutil.py

from datetime import datetime

def days_to_snake_day(from_date=None):
    """Return the number of days until World Snake Day (July 16th)."""
    if from_date is None:
        from_date = datetime.now()
    if from_date.month > 7 or (from_date.month == 7 and from_date.day > 16):
        day_of_snake = datetime(from_date.year + 1, 7, 16)
    else:
        day_of_snake = datetime(from_date.year, 7, 16)
    return (day_of_snake - from_date).days

# snake-corp-dateutil/pyproject.toml

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["."]
include = ["snake_corp"]
namespaces = true

[project]
name = "snake-corp-dateutil"
version = "1.0.3"
description = "Date Utilities for the Snake Corporation"
license = { text = "Snake Corp Software License Agreement" }

# snake-corp-magic-numbers/snake_corp/magic.py

import random

def secret_number_generator():
    # Insert special Snake Corporation sauce here ...
    return random.randint(0, 9999)

# snake-corp-magic-numbers/pyproject.toml

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["."]
include = ["snake_corp"]
namespaces = true

[project]
name = "snake-corp-magic-numbers"
version = "1.1.8"
description = "Super Magic Secret Numbers for the Snake Corporation"
license = { text = "Snake Corp Software License Agreement" }

PS> python -m venv venv
PS> venv\scripts\activate
(venv) PS> python -m pip install -e snake-corp-dateutil\
(venv)