docs: update tutorial to use uv #518
Conversation
samcunliffe
requested review from
matt-graham and
a team
and removed request for
samcunliffe
There was a problem hiding this comment.
Thanks so much for picking this up!
I'm probably not a good reviewer though: I only have access to macOS and Ubuntu.
(Kinda related: should we think about running the tutorial again in the next ARC Festival of ...? I guess that's more of a question to the ether.)
tutorial.md
Outdated
| conda create -y -n python-tooling -c conda-forge cookiecutter git gh pre-commit tox | ||
| uv tool install cookiecutter | ||
| uv tool install pre-commit | ||
| uv tool install tox |
There was a problem hiding this comment.
Do they really need tox and pre-commit?
tutorial.md
Outdated
|
|
||
| and ideally also, | ||
| Additionally, [pre-commit](https://pre-commit.com/) and [tox](https://tox.wiki) are required to complete some of the follow on steps for using the package generated with the template, so while they are not strictly needed, you will get more out of the tutorial if you have them installed. For the follow on exercises you will also need an [account set up on GitHub](https://github.com/join) if you don't already have one. |
There was a problem hiding this comment.
| Additionally, [pre-commit](https://pre-commit.com/) and [tox](https://tox.wiki) are required to complete some of the follow on steps for using the package generated with the template, so while they are not strictly needed, you will get more out of the tutorial if you have them installed. For the follow on exercises you will also need an [account set up on GitHub](https://github.com/join) if you don't already have one. | |
| Additionally, [pre-commit](https://pre-commit.com/) and [tox](https://tox.wiki) are required to complete some of the follow along steps for using the package generated with the template, so while they are not strictly needed, you will get more out of the tutorial if you have them installed. For the follow along exercises you will also need an [account set up on GitHub](https://github.com/join) if you don't already have one. |
There was a problem hiding this comment.
"Follow on" is correct here for the sense of "things following on from" which is what I intended when I originally wrote this in the context of running this as a tutorial at the festival. "Follow along" would I think change the meaning
There was a problem hiding this comment.
When reading it, I genuinely wasn't sure what was intended. If it's that use case then I think we should use following.
tutorial.md
Outdated
| uv tool install cookiecutter | ||
| uv tool install pre-commit | ||
| uv tool install tox |
There was a problem hiding this comment.
Not with one uv command - uv tool install --help gives usage as
Usage: uv tool install [OPTIONS] <PACKAGE>
and trying with multiple package names gives an error.
It might be possible to stack multiple commands on a line using separators but I'm not sure if this would be easy to do in a way that will work across operating system / shells and also would probably be less readable.
There was a problem hiding this comment.
We don't need pre-commit and tox so that should solve it.
There was a problem hiding this comment.
Thanks @Saransh-cpp for the updates, this mostly looks great to me. I've tested setting up uv on Windows and installing the tools as explained in the text and it all worked fine. I've added a few comments - main one is that I think the section on installing dependencies may need reworking a bit to make it clearer that Git and GitHub CLI will need to be installed separately, as previously conda was also being used to install these.
tutorial.md
Outdated
|
|
||
| and ideally also, | ||
| Additionally, [pre-commit](https://pre-commit.com/) and [tox](https://tox.wiki) are required to complete some of the follow on steps for using the package generated with the template, so while they are not strictly needed, you will get more out of the tutorial if you have them installed. For the follow on exercises you will also need an [account set up on GitHub](https://github.com/join) if you don't already have one. |
There was a problem hiding this comment.
"Follow on" is correct here for the sense of "things following on from" which is what I intended when I originally wrote this in the context of running this as a tutorial at the festival. "Follow along" would I think change the meaning
tutorial.md
Outdated
| uv tool install cookiecutter | ||
| uv tool install pre-commit | ||
| uv tool install tox |
There was a problem hiding this comment.
Not with one uv command - uv tool install --help gives usage as
Usage: uv tool install [OPTIONS] <PACKAGE>
and trying with multiple package names gives an error.
It might be possible to stack multiple commands on a line using separators but I'm not sure if this would be easy to do in a way that will work across operating system / shells and also would probably be less readable.
There was a problem hiding this comment.
Thanks @Saransh-cpp for the updates, all looks good to me 😍!
There was a problem hiding this comment.
Aaah down on 289 we're telling them to use tox. So perhaps we should tell them to install tox around there.
uv tool install tox
... ? Ditto pre-commit down at 312.
(Sorry @Saransh-cpp I gave you a wrong comment 🙃 )
But perhaps installing them should come later around the relevant section of the tutorial?
|
|
||
| An alternative to Conda is the [`venv` module](https://docs.python.org/3/library/venv.html) built-in to the Python standard library. This has the advantage of being available in any Python (3.3+) environment, but unlike Conda will not by itself allow you to use a different Python version from the system level install. In contrast to Conda which by default creates all environments in a shared user-level directory (if using Miniconda, by default in a directory `miniconda3/envs` in your user or home directory), the `venv` module requires being passed a path in which to create the directory containing the files associated with the virtual environment. A common pattern is to store the virtual environment files in a directory `.venv` within the root directory of the project repository. This can be achieved by running | ||
| Alternatively, you can use the [`venv` module](https://docs.python.org/3/library/venv.html), which is slower and has fewer features, when compared to `uv`, but is built-in to the Python standard library. `venv` has the advantage of being available in any Python (3.3+) environment, but unlike `uv` will not by itself allow you to use a different Python version from the system level install. A common pattern is to store the virtual environment files in a directory `.venv` within the root directory of the project repository. This can be achieved by running |
There was a problem hiding this comment.
I just ran through these for sanity as a fresh user in macOS.
The only stumbling point is from here on, it's not clear that we should preferentially be using UV.
That Is, if I skip or skim read the "Alternatively..." part and then try to python -m pip install X I will get:
(python-template) teaching@scafell python-template % python -m pip install numpy
/Users/teaching/python-template/.venv/bin/python: No module named pip
Obviously because I didn't install pip in my venv. But I should be running uv pip install all the time.
Should we cull some of the information that follows? Or put it into a <details></details> block to hide it away?
I think we want to end the </details> block around
263 Once you have created and activated a virtual environment for the project, ...
Because the uv users (who will be in the majority?) will also need to install their own package into the uv venv.
Line 266 teaches them to install the dev and test dependencies for the package, and I think this is getting shadowed by the whole |
Oh, great! |
Removed conda and introduced uv for everything.
Reviewed the tutorial on a Windows machine.
Closes #477