[hatchling] Improve errors / diagnostics when package is missing __init__.py

[drmason13]

I'm sorry if the (user facing) error reporting out of hatchling is out of scope, I've seen this from uv while using hatchling as a build backend. I might get told by both projects that it is something the other project should fix 🙂

I'm afraid I don't know the reproduction steps using hatchling directly, so I'll describe what happened when using uv.

Here's my build-system from pyproject.toml. It's pretty typical:

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

Running uv build in a project which is laid out in a typical style:

pyproject.toml
src/
    my_project/
        < distinct lack of __init__.py >

I've seen this error a few times:

The most likely cause of this is that there is no directory that matches the name of your project (my_project)

but it can be a confusing and frustrating error when there is a directory with that name.

The actual problem is that python doesn't recognise the directory as a module/package due to the lack of __init__.py.

Forgetting/losing your __init__.py is a silly error to make but I think it's common enough that it is worth mentioning in this error message/suggestion that your directory also needs an __init__.py. You've done the hard part in naming the directory that is problematic.

I might suggest the following:

The most likely cause of this is that there is no directory that matches the name of your project (my_project) or that directory does not contain an __init__.py file.

Before

ValueError: Unable to determine which files to ship inside the wheel using the following heuristics: https://hatch.pypa.io/latest/plugins/builder/wheel/#default-file-selection

The most likely cause of this is that there is no directory that matches the name of your project (my_project).

At least one file selection option must be defined in the `tool.hatch.build.targets.wheel` table, see: https://hatch.pypa.io/latest/config/build/

As an example, if you intend to ship a directory named `foo` that resides within a `src` directory located at the root of your project, you can define the following:

[tool.hatch.build.targets.wheel]
packages = ["src/foo"]

After

ValueError: Unable to determine which files to ship inside the wheel using the following heuristics: https://hatch.pypa.io/latest/plugins/builder/wheel/#default-file-selection

The most likely cause of this is that there is no directory that matches the name of your project (my_project) or that directory does not contain an __init__.py file.

At least one file selection option must be defined in the `tool.hatch.build.targets.wheel` table, see: https://hatch.pypa.io/latest/config/build/

As an example, if you intend to ship a directory named `foo` that resides within a `src` directory located at the root of your project, you can define the following:

[tool.hatch.build.targets.wheel]
packages = ["src/foo"]

Bonus points if hatchling actually checks and works out what is missing: __init__.py or the directory

Here is the issue I raised over at uv: astral-sh/uv#8212.
I've removed what I believe to be unnecessary uv-specifics in this issue.