hatch vs uv

[grst]

We currently suggest to use hatch with a uv backend.

However, uv is already a quite powerful project management tool by itself.
The only piece that seems to be missing is a definition of development commands, such as

[tool.hatch.envs.docs]
features = [ "doc" ]
scripts.build = "sphinx-build -M html docs docs/_build {args}"

But there's an active discussion to support that as well: astral-sh/uv#5903.

[flying-sheep]

Thanks for the pointer! I don’t think keeping this open makes sense at the moment though.

Hatch’s environment definition is pretty fully-featured and mature. I don’t think uv can catch up within a few months (if they decide to grow that feature at all).

[grst]

Hi @flying-sheep , I'm more wondering if we even need the additional features provided by hatch.
If we really want to offer task definitions we could as well include an old-fashioned Makefile.

And at this point I think the community has very much embraced uv, while I have the feeling that nobody even has heard of hatch. And instead of learning to hatch run test I can as well learn to type uv run pytest.

I'm not totally against hatch, but it adds some additional layer of abstraction of which I'm not sure it's necessary. If we go for hatch, then we should fully commit to it (#332 , #368). And this is something I'd like to reach a decision on before making a release within the next week or so.

[ofek]

old-fashioned Makefile

That doesn't work on Windows.

[flying-sheep]

I'm more wondering if we even need the additional features provided by hatch.

I think that having a separate docs and hatch-test environment is a killer feature for everyone (nobody wants to debug why some constraint of some doc dependency caused your tests to fail). Having a test matrix locally without having to deal with tox is very very useful as well, although maybe not everyone needs it.

I have the feeling that nobody even has heard of hatch.

This feeling isn’t true, there are a lot of users, and it’s prominiently featured in popular packaging tutorials:

• https://hatch.pypa.io/latest/community/users/
• https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-build-tools.html
• https://packaging.python.org/en/latest/tutorials/packaging-projects/

I'm not totally against hatch, but it adds some additional layer of abstraction of which I'm not sure it's necessary.

You think that teaching users to create and manage venvs manually helps them understand what they’re doing more, right? That’s valid, but I think the added convenience of using a project manager like Hatch is worth it.

And hatch env prune isn’t that much more complicated than rm -rf venv*

That doesn't work on Windows.

I guess just would work, but as said, I think having environment management tied in with the job running is very useful.

[grst]

I have the feeling that nobody even has heard of hatch.

This feeling isn’t true, there are a lot of users, and it’s prominiently featured in popular packaging tutorials:

This was mostly based on conversations I had at the hackathon. But ofc this is not representative

Just played around a bit with hatch in one of my projects. I like the local test matrix feature and in principle it's neat that the exact testing command and docs build command is defined in the pyproject.toml.

One thing I don't like is that I need to run hatch env find hatch-test to get the environment path and tell vscode manually to use this. uv creates the env in .venv which is auto-detected by vscode (and probably other IDEs). But I can see how this is incompatible with having multiple environments per project.

[ofek]

Can you please verify that this works? https://hatch.pypa.io/latest/how-to/integrate/vscode/

[grst]

Hi @ofek,

thanks, this works (but I had to install hatch globally as mentioned in the page you shared). Before I had just installed it via uv.

[flying-sheep]

Environment discovery should really be standardized, it’s sad that vscode-python natively finds conda envs but not hatch envs. (OK, I could fix that by making that extension, but that’s so much work)

Before uv is a good alternative to Hatch IMHO it needs to figure out

• specifying multiple environments with a reasonable amount of freedom
• locking them individually (so far there’s only one lockfile)
• specifying script running per environment

nothing of the above exists even conceptually in uv.

@grst has this issue been settled for now in your opinion?

[grst]

Right now, in the contribution guide, we recommend hatch, but also show how pip can be used instead. I think it's a good thing to not be overly opinionated here: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/contributing.html#contributing-guide

We could just keep doing that and possibly add another tab for uv, while we clearly recommend hatch as the preferred tool?

I am, however, convinced now, that uv cannot serve as a drop-in replacement for hatch, and likely will not be expanded in scope to ever be.

[flying-sheep]

Right now, in the contribution guide, we recommend hatch, but also show how pip can be used instead

Hmm, that wouldn’t be possible anymore if we get rid of the doc and test extras, which I think we should if we do CI with Hatch. What do you think?

[grst]

That's the part where I'm not entirely sure. Why go for non-standardized hatch-test.dependencies if we can easily support other workflows with dependency groups? At least until there's an official standard for dev dependencies available. Maybe something we can take up in a core dev meeting, too.

[flying-sheep]

Well, as said in the PR, because extras/optional features end up in the package metadata and therefore don’t exist for developers of the package, but for users, i.e. people who install the package as a dependency.

So it would be nice to clean up the hack of misusing the extras, but I’m not super strong on this, it’s not a big issue to expose this, at most it’s a bit confusing for users.

[grst]

PEP735 has actually been accepted, is already implemented in uv and a PR is underway for hatch. So I think it's worth waiting for that and not changing the current setup using "extras" until then.