Building Namespaced Packages

[geudrik]

I'm struggling to get reliable name-space packages building.

I have several different projects, each building a package. Each package provides a different "thing" within the namespace, and the folder structure of the namespace (and each) package is tightly defined.

team-package1

... other files in my repo ...
theNamespace/
    intermediate/
        package1/
            __init__.py  # In this package, this is the only file, and it has things in it that you'd import

team-package2

... other files in my repo ...
theNamespace/
    intermediate/
        package2/
            __init__.py
            my_thing.py

In each pyproject.toml file, I've got this for my build target

edit: here's the complete pyproject.toml for the failing build (where the .whl is just empty)

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "thing-env"
version = "1.0.0"
description = "Easy environment var grabbing"
authors = [{ name = "user", email = "email@domain.com" }]
requires-python = ">=3.12"

[tool.hatch.build.targets.wheel]
packages = ["theNamespace"]

When building the second team package, my whl contains the full folder structure and files. But when I build my first team package, absolutely nothing is included.

What am I doing wrong here?

[geudrik]

So this is puzzling. The package with just an __init__.py file, I changed out for a named file, and did an import with ALL in the init, and still hatch fails to find and package during a uv build. Running uv build -vvv doesn't tell me anything, but there are two lines that say Ignoring empty directory, (they're DEBUG lines), and there's no useful context around what they mean (eg: what dirs, and what's going on when that debug line is printed)

Even more puzzling, the second package, which has the SAME TWO INTERMEDIATE directories that are empty (per PEP-420), is bundled and packaged correctly. This library has about 100 LOC in total, the first (the one that isn't being picked up) is a single class, with 3 classmethods, and is 24 LOC (including newlines and the final empty line, IDK if this matters)

[SirHegel]

The configuration is not the problem (the second package proves it), so the difference is in the paths. Hatchling applies the repository's .gitignore to file selection by default, and packages = [...] does not override that. A pattern such as env/, build/, lib/ or tmp/ matches a directory with that name at any depth, theNamespace/intermediate/<name>/ included, and everything under it is left out of the wheel. A package for "environment var grabbing" is a likely victim of the env/ line that ships in nearly every Python .gitignore template. Check it directly from the repository root:

git check-ignore -v theNamespace/intermediate/<package>/__init__.py

If that prints a pattern, that is the cause. Reproduced with hatchling 1.32.0: a repository whose .gitignore contains env/ and a package at theNamespace/intermediate/env/__init__.py with packages = ["theNamespace"] builds a wheel that contains only the .dist-info directory, which is the symptom you describe. Fixes, in order of preference: rename the directory; re-include it after the generic pattern in .gitignore (!theNamespace/intermediate/<package>/); or make the wheel target ignore VCS files (both of the last two restore the file in the reproduction above):

[tool.hatch.build.targets.wheel]
packages = ["theNamespace"]
ignore-vcs = true

If git check-ignore prints nothing, compare git ls-files theNamespace between the two repositories and post the result; the remaining candidates are a .gitignore in a parent directory (Hatchling uses the first one found walking up from the project root, not beyond the repository root) or an exclude pattern in a [tool.hatch.build] table that is not in the excerpt.

References:

• https://hatch.pypa.io/latest/config/build/#vcs
• https://github.com/pypa/hatch/blob/929362c909899556ae4efd1f61a3b078677ad235/backend/src/hatchling/builders/config.py (vcs_exclusion_files, load_vcs_exclusion_patterns)