Add uv support for development environment

[Itz-Agasta]

Summary

• Add a root pyproject.toml with uv workspace configuration and dev dependency groups, enabling contributors to use uv as an alternative to the existing virtualenv + pip workflow.
• Add documentation for using uv in the dev environment setup.

How it works

Contributors using uv can set up their env with a single command:

uv sync
# This installs runtime dependencies (from the package pyproject.toml files)
# and all dev tools (pytest, mypy, flake8, mkdocs, etc.) into a local .venv.

# Individual groups can be installed separately:
uv sync --group test --no-dev    # Only test dependencies
uv sync --group docs --no-dev    # Only docs dependencies
uv sync --group serve --no-dev   # Only server dependencies

NOTE: uv.lock is in .gitignore as per project policy.... each developer resolves dependencies locally. For more info refer to the thread #4044

AI usage

None

Contributor guidelines (mandatory)

• I have adhered to the coding style
• I have tested the proposed changes
• I have disclosed above any use of AI to generate code, documentation, or the pull request description

[Itz-Agasta]

Demo

2026-03-24.23-22-30.mp4

This is a testing rollout; the CI hasn’t been touched yet.

[lonvia]

Finally got around trying this out. It's a very nice solution to #4022, even for the pip users, and uv opens up testing against other python versions.

Having the dependencies in the root pyproject.toml also makes much more sense because development only happens on the full package. The only optional dependencies that are not always development-related are around serving. But even there it makes sense to have different extra groups (see comment on gunicorn). Something to think about separately.

I've added small comments. Let me know what you think about them.

[lonvia]

The dependency groups work nicely with pip as well:

~/nominatim-dev-venv/bin/pip install --group dev

Sadly this isn't a complete replacement for the command above because the required dependencies that are defined in the packages are missing. If there isn't a way to pull them from the subpackages automatically, I'm leaning towards adding another dependency group with those requirements. It'd still be a duplication but in contrast to the line above in the documentation it could be tested in the CI to ensure it stays up-to-date.

[Itz-Agasta]

I'm leaning towards adding another dependency group with those requirements.

I will argue with that, i dont think it will a good idea to manage dependencies form two files lt might raise ambiguity later.

I would say lets make the root pyproject.toml a proper package (nominatim) that declares nominatim-api and nominatim-db as its dependencies. With this in place,

 pip install --group dev .

It will does everything in one-shot, Installs nominatim-api and nominatim-db (and their deps) via [project].dependencies and installs all dev tooling via --group dev

[lonvia]

We unfortunately can't have a package "nominatim". The name is already used and I won't to avoid confusion at any cost. I've contacted the owner but with no success so far.

The other thing to note is that for my use-case I don't want nominatim-{api,db} themselves installed in the virtual environment. I just want the dependencies, i.e. a virtualenv with which I can then run the nominatim-cli.py script in place.

Oh well, this is just a nice-to-have. Lets defer it to later.

[Itz-Agasta]

I had to pin mypy to <=1.19.1.... As v 1.20 giving false positives locally

Not related to uv. i have tested with pip too

Mypy 1.20 changed how it handles attribute access on class objects vs instances also some breaking changes.

Refs:

• "note: unused section(s)" incompatible with command line list of files python/mypy#21137
• 1.20 and 2.0 Release Planning python/mypy#20726

Idk what y recommend for this ?

[lonvia]

Those mypy issues are fixed on master. Simply rebase.

[Itz-Agasta]

Those mypy issues are fixed on master. Simply rebase.

ohh my bad :( ... done

[lonvia]

Can we go back to the version without a project in the base pyproject.toml?

[Itz-Agasta]

Pls have a look now... I’ve added the runtime group as y mentioned... Also i noticed that you’ve added the async version of SQLAlchemy in the API deps, so updated the dev docs accordingly.

and sorry for the communication delay.. my end sem exams are on-going :(

[lonvia]

Thanks and sorry for the long wait.