docs: update tutorial to use uv #518

Saransh-cpp · 2025-02-11T21:45:40Z

Removed conda and introduced uv for everything.
Reviewed the tutorial on a Windows machine.

Closes #477

tutorial.md

samcunliffe

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.)

samcunliffe · 2025-02-12T13:09:16Z

tutorial.md

-   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


Do they really need tox and pre-commit?

We don't! Thanks!

paddyroddy

A few comments

paddyroddy · 2025-02-12T13:13:52Z

tutorial.md

+- [the GitHub command line interface (CLI)](https://github.com/cli/cli?tab=readme-ov-file#installation)

-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.


Suggested change

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.

"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

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

paddyroddy · 2025-02-12T13:18:33Z

tutorial.md

+   uv tool install cookiecutter
+   uv tool install pre-commit
+   uv tool install tox


Can these be one line?

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.

We don't need pre-commit and tox so that should solve it.

tutorial.md

matt-graham

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.

matt-graham · 2025-02-12T14:04:00Z

tutorial.md

+- [the GitHub command line interface (CLI)](https://github.com/cli/cli?tab=readme-ov-file#installation)

-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.


"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

matt-graham · 2025-02-12T14:09:13Z

tutorial.md

+   uv tool install cookiecutter
+   uv tool install pre-commit
+   uv tool install tox


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.

tutorial.md

Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>

tutorial.md

matt-graham

Thanks @Saransh-cpp for the updates, all looks good to me 😍!

samcunliffe

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?

samcunliffe · 2025-02-13T11:10:09Z

tutorial.md

+```

-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


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.

Saransh-cpp · 2025-02-13T11:25:39Z

Aaah also down on 289 we're ...

Line 266 teaches them to install the dev and test dependencies for the package, and tox + pre-commit are bundled within those groups (which should actually use uv, fixing this too) 😉

I think this is getting shadowed by the whole venv stuff, which yes, should be in a </details> block. I'll update it. Thanks!

samcunliffe · 2025-02-13T11:27:02Z

Line 266 teaches them to install the dev and test dependencies for the package, and tox + pre-commit are bundled within those groups (which should actually use uv, fixing this too) 😉

Oh, great!

samcunliffe

Perfect. Cheers!

samcunliffe · 2025-02-18T16:31:46Z

I forgot!

@all-contributors please add @Saransh-cpp for docs, content, maintenance, review

allcontributors · 2025-02-18T16:31:57Z

@samcunliffe

I've put up a pull request to add @Saransh-cpp! 🎉

@Saransh-cpp

…521) Adds @Saransh-cpp as a contributor for doc, content, maintenance, review. This was requested by samcunliffe [in this comment](#518 (comment)) --------- Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com>

docs: update tutorial to use uv

09ba663

Saransh-cpp commented Feb 11, 2025

View reviewed changes

tutorial.md Outdated Show resolved Hide resolved

tutorial.md Outdated Show resolved Hide resolved

tutorial.md Outdated Show resolved Hide resolved

tutorial.md Outdated Show resolved Hide resolved

tutorial.md Outdated Show resolved Hide resolved

tutorial.md Outdated Show resolved Hide resolved

Saransh-cpp added 3 commits February 11, 2025 21:47

uniform punctuations

ba7ecb1

update gh installation instruction

2c85299

fixes for windows

c9fcc84

Saransh-cpp marked this pull request as ready for review February 12, 2025 11:52

Saransh-cpp requested review from paddyroddy and samcunliffe February 12, 2025 11:53

samcunliffe requested review from a team and matt-graham and removed request for samcunliffe February 12, 2025 13:07

samcunliffe reviewed Feb 12, 2025

View reviewed changes

samcunliffe requested a review from a team February 12, 2025 13:11

paddyroddy approved these changes Feb 12, 2025

View reviewed changes

matt-graham reviewed Feb 12, 2025

View reviewed changes

Saransh-cpp and others added 3 commits February 12, 2025 14:36

language

1a0449f

Co-authored-by: Patrick J. Roddy <patrickjamesroddy@gmail.com>

we do not need tox and pre-commit

aef4cac

more explicit about installation

072d437

Saransh-cpp commented Feb 12, 2025

View reviewed changes

tutorial.md Outdated Show resolved Hide resolved

them -> the

1c19d0e

Saransh-cpp requested review from matt-graham and samcunliffe February 12, 2025 14:50

matt-graham approved these changes Feb 12, 2025

View reviewed changes

samcunliffe reviewed Feb 13, 2025

View reviewed changes

Saransh-cpp added 3 commits February 13, 2025 11:32

better distinction between venv and uv

5532011

better summary

5823dd0

rearrage text

21ae8da

Saransh-cpp requested a review from samcunliffe February 13, 2025 11:36

samcunliffe approved these changes Feb 13, 2025

View reviewed changes

Saransh-cpp merged commit e5d3bf0 into main Feb 14, 2025
13 checks passed

Saransh-cpp deleted the saransh/update-tutorial branch February 14, 2025 14:49

allcontributors bot mentioned this pull request Feb 18, 2025

docs: add Saransh-cpp as a contributor for doc, content, and 2 more #521

Merged

docs: update tutorial to use uv #518

docs: update tutorial to use uv #518

Uh oh!

Conversation

Saransh-cpp commented Feb 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

samcunliffe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paddyroddy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matt-graham Feb 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

matt-graham left a comment

Choose a reason for hiding this comment

Uh oh!

matt-graham Feb 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matt-graham left a comment

Choose a reason for hiding this comment

Uh oh!

samcunliffe left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Saransh-cpp commented Feb 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

samcunliffe commented Feb 13, 2025

Uh oh!

samcunliffe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samcunliffe commented Feb 18, 2025

Uh oh!

allcontributors bot commented Feb 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

Saransh-cpp commented Feb 11, 2025 •

edited

Loading

matt-graham Feb 12, 2025 •

edited

Loading

matt-graham Feb 12, 2025 •

edited

Loading

samcunliffe left a comment •

edited

Loading

Saransh-cpp commented Feb 13, 2025 •

edited

Loading