Project directory structure

[pkucmus]

Hello.

[UV: 0.4.6, Python: 3.12.4]

(I'm using Poetry since it's inception, so I might be opinionated, but I'm learning a lot when going through the issues here - if something might sound like a "Poetry user's opinion" feel free to call me out :))

I'm also quite opinionated when it comes to the project directory structure, what you propose here, for projects leads into other challenges down the line, like being forced to "dance around" the .venv directory in Docker.

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── hello.py
├── pyproject.toml
└── uv.lock

Where if you were to "src the project", like so:

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── src
│   └── my_project
│       └── hello.py
├── .python-version
├── README.md
├── pyproject.toml
└── uv.lock

Then a few things can happen:

1. You can Docker volume everything that's in src

services:
  my_project:
    ...
    volumes:
      - ./src:/app/src

2. You can leverage Docker cache in build time if the dependencies did not change

FROM python:3.12
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

...

WORKDIR /app

COPY uv.lock pyproject.toml ./

ARG INSTALL_DEV=false
RUN uv sync --frozen --no-install-project
COPY . .  
RUN uv sync --frozen

don't redo the dependency installation if uv.lock or pyproject.toml did not change

3. you can explicitly reference your root project with

from my_project import hello

This approach should be doable with a pyproject.toml addition of:

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

[tool.hatch.build]
include = [
    "src/my_project",
]

but for some reason my_project is not available for import.

[zanieb]

Have you tried uv init --package? I believe it creates the structure you're looking for.

See https://docs.astral.sh/uv/concepts/projects/#packaged-applications

[pkucmus]

Thanks for all you help on these, the issue was different and it's more likely related to the hatchling.build - __init__.py was missing from my root module (which Poetry did not care about).
This "opinionated setup" of mine should be doable now but I'm curious about one more thing: can I have more than one root package in src? Same as https://python-poetry.org/docs/pyproject/#packages?

Also I'm curious how does everyone find the src approach for projects in general, is it at least worth mentioning in the docs?

[zanieb]

Yeah totally. This is all build backend configuration. We don't provide our own build backend yet (#3957) but I believe hatchling supports what you're describing or you could use another build backend like setuptools: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html

There's also https://docs.astral.sh/uv/concepts/workspaces/ if you have more complicated setups.

[sirosc]

One way of doing it in pyproject.toml with hatch is:

[tool.hatch.build.targets.wheel]
# Defines the targets for the wheel build.
include = ["src/my_project1/**", "src/my_project2/**"]