experiment: migrate to uv as package manager

[danieleades]

This is an experiment in using UV as a package manager. This project currently does not use a package manager.

This PR is not intended to be merged as is, but to serve as a way to discuss a potential migration. Even if such a migration is desirable, it doesn't necessarily mean it should happen now. UV is very promising, but still very new.

No migration should be considered unless the following criteria can be met:

• no loss of functionality of features compared to existing solution
• comprehensive documentation of new workflows and migration path from old workflows
• minimal effort for existing contributors to migrate to new workflow
• no increased effort to onboard new contributors
  • for new developers not already familiar with the process of setting up the Sphinx dev environment manually, uv is significantly easier to get started, eg. git clone https://github.com/sphinx-doc/sphinx.git && cd sphinx && uv run pytest
• clear demonstration of benefits of migration in terms of
  • CI performance
  • developer convenience
  • simplicity of configuration of CI jobs, scripts, etc.

Known Limitations

• UV and Tox have overlapping functionality, which is not ideal. We could continue to use both, but ideally we'd solve both use cases with one tool
  • Both tools manage virtual environments. Seems silly to have two different approaches to the same problem
  • Tox is very slow to install dependencies compared to UV. This can be mitigated using the tox-uv plugin
  • UV can run tests against target python versions just like Tox, but doesn't have any built-in way of running against a matrix of python versions with a single command for local testing.

[AA-Turner]

Thank you for trying this, and I appreciate experimenting with managing packaging, but to set expectations I don't think it's likely we'll merge anything like this unless it is (a) entirely optional for contributors and (b) backwards compatible (unless the entire ecosystem switches overnight).

The example I'd use is Tox, which is set up, but optional and not needed to make contributions.

A

[AA-Turner]

This will use the released version of Sphinx rather than the development version.

[danieleades]

why do you say that?

[danieleades]

Thank you for trying this, and I appreciate experimenting with managing packaging, but to set expectations I don't think it's likely we'll merge anything like this unless it is (a) entirely optional for contributors and (b) backwards compatible (unless the entire ecosystem switches overnight).

The example I'd use is Tox, which is set up, but optional and not needed to make contributions.

A

What do you mean by "backwards-compatible" here?

[AA-Turner]

What do you mean by "backwards-compatible" here?

Mainly identical functionality to the status quo.

A

[danieleades]

Thank you for trying this, and I appreciate experimenting with managing packaging, but to set expectations I don't think it's likely we'll merge anything like this unless it is (a) entirely optional for contributors and (b) backwards compatible (unless the entire ecosystem switches overnight).

The example I'd use is Tox, which is set up, but optional and not needed to make contributions.

A

using UV would not be optional for contributors as it will be needed for bootstrapping the dev dependencies.

I think having "zero change to contributor workflow" should not be the goal. I think the goals should be:

1. acceptable change to workflow for existing contributors
2. easier onboarding for new contributors

I think goal 2. is absolutely satisfied. the workflow will change from:

git clone https://github.com/sphinx-doc/sphinx.git && cd sphinx
sudo apt update
sudo apt install python3-venv
python3 -m venv .venv && . ./.venv/bin/activate && python -m pip install ".[lint,test,docs]"
pytest

to:

git clone https://github.com/sphinx-doc/sphinx.git && cd sphinx
curl -LsSf https://astral.sh/uv/install.sh | sh
uv run pytest

I think that's much easier, and doesn't require new contributors to grok virtualenvs. That's without getting into the benefits of increased speed, dependency management (adding, updating, removing), reproducible environments, etc.

Goal 1. is far more subjective. The purpose of this PR is to provide an opportunity to play around and build consensus. If you have time i highly recommend cloning this and playing around with the UV cli

[picnixz]

The fact that uv is not in distribution packages is what would stop me from helping. I personally prefer the virtual environment approach. I'm also unsure whether uv is known or not to contributors in general. This will be something new to teach (and to digest for old contributors). So I'm personally -0.5 (I wouldn't say outright -1 but I'm < 0).

In addition: "UV can run tests against target python versions just like Tox, but doesn't have any built-in way of running against a matrix of python versions with a single command for local testing." This is something that I like having for tox and is also very useful for autodoc related things (due to how typing changes across versions...). It's not really a blocker but I'd prefer not to switch to UV for now.

[chrisjsewell]

the workflow will change from

as already mentioned, you don't need all these steps for the existing configuration, and can still use uv with it, if you just use tox-uv (which I do)

[danieleades]

the workflow will change from

as already mentioned, you don't need all these steps for the existing configuration, and can still use uv with it, if you just use tox-uv (which I do)

can you use tox without manually setting up the virtual environment and still have the IDE running within the dev environment?

[chrisjsewell]

can you use tox without manually setting up the virtual environment and still have the IDE running within the dev environment?

yep

[danieleades]

The fact that uv is not in distribution packages

what does this mean?

I personally prefer the virtual environment approach.

note that UV still uses a virtual environment, named '.venv' and stored in the project root. UV just manages the packages in it for you

[danieleades]

can you use tox without manually setting up the virtual environment and still have the IDE running within the dev environment?

yep

can you use tox without manually setting up the virtual environment and still have the IDE running within the dev environment?

yep

might be something worth documenting in the 'internals' docs...

using tox-uv sounds like a good optimisation of the current framework. It doesn't address the package management features though- namely version resolution, reproducible environments (through dependency locking), etc.

[picnixz]

what does this mean?

I need to install it via an sh script instead of an apt-get install. (should have said that there are no official repositories). When I said "would stop me from helping", it's not really me personally, but rather contributors that either want official pip packages or packages that are available from their distributions.

My main argument against uv (for now) is that you'll need to change the way you launch your tests. uv run pytest versus pytest for instance. I confess that I also never used uv so maybe it's a great tool! By the way, I'm not sure if the workflow:

sudo apt update
sudo apt install python3-venv
python3 -m venv .venv && . ./.venv/bin/activate && python -m pip install ".[lint,test,docs]"

is actually needed. I think venv is already bundled with python so you just need:

python3 -m venv .venv && source .venv/bin/activate && pip install -e .

[picnixz]

I need to install it via an sh script instead of an apt-get install.

Nevermind it appears that there is a pip package as well.

[chrisjsewell]

this should wait on astral-sh/uv#5632, i.e. we shouldn't need to collapse all the dev dependencies into a single list

[danieleades]

could do. This might be premature optimisation though as the current dev dependencies-

• install very quickly using UV
• have no conflicts

based on that i think splitting them into separate groups might be a micro-optimisation

[chrisjsewell]

Nothing to do with speed: you are forcing all test environments to have unnecessary resolve constraints against unrelated packages, which can change the versions of packages you get

[danieleades]

yep, this is true in the general case. that also introduces the risk that different contributors resolve different versions depending on whether they are also building the docs, for example. Since even with dependency groups, the groups are not isolated from each other

Since even with dependency groups, the groups are not isolated from each other

i guess i'm speculating here, since the feature doesn't exist yet.

Still, i'm not sure it's a blocker. Certainly isn't causing any issues with the dependencies in sphinx today

[zanieb]

As of 0.4.27, uv supports separate groups. They still will constrain each other though, as the lockfile is for the entire project.

[danieleades]

My main argument against uv (for now) is that you'll need to change the way you launch your tests. uv run pytest versus pytest for instance.

it doesn't have to, uv run is just a convenience.

UV still creates a virtual environment, so if you want to run pytest without the uv run prefix you absolutely can. These are equivalent (and both are supported when using UV):

source .venv/bin/activate
pytest

vs

uv run pytest

uv run is just shorthand for "run the following command inside the virtual environment"

[picnixz]

Mmh. So to summarize, we could drop pip + venv and have uv instead? It could convince me and it reminds me of npm a bit. The argument of uv is that it's fast compared to pip. If this is the case, it could be an advantage. If we can make uv compatible with tox (i.e., switching to uv without changing the workflow of people using tox), then it will be good.

I need to play with uv myself to convince me but the concerns I have are not that much. Also, CPython switched to uv for docs so I'll probably need to adopt it at some point. The only concern is about the lack of matrix tests but we can probably supply some makefile rule that would do the job.

[danieleades]

Mmh. So to summarize, we could drop pip + venv and have uv instead?

yep. it also replaces pyenv if you happen to use that.

If we can make uv compatible with tox (i.e., switching to uv without changing the workflow of people using tox), then it will be good.

The only concern is about the lack of matrix tests but we can probably supply some makefile rule that would do the job.

i agree. I don't love the idea of having multiple ways to manage virtualenvs and i think a makefile rule wrapping a matrix is probably not a terrible solution

[jayaddison]

If possible: could we use the astral-sh/setup-uv GitHub Action here, instead of installing from a hosted scriptfile?

[jayaddison]

Ah: I notice we're already using the scriptfile version in a few workflows. Ignore me; I'll suggest that we migrate them collectively.