From 09ba66347f2f0f00c4c6cd92bb81cca8b8f934b4 Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Tue, 11 Feb 2025 21:42:23 +0000 Subject: [PATCH 01/11] docs: update tutorial to use uv --- tutorial.md | 94 +++++++++++++++++++++++------------------------------ 1 file changed, 41 insertions(+), 53 deletions(-) diff --git a/tutorial.md b/tutorial.md index faaab747..d353d99d 100644 --- a/tutorial.md +++ b/tutorial.md @@ -9,49 +9,30 @@ In this tutorial we will go through in detail the steps required to set-up a Pyt
Click to expand... -To use the template you will need to have at least the following software tools installed, +To start using the template you will need at least the following software tools installed: -- [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/), -- [Git](https://git-scm.com/), +- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +- [uv](https://docs.astral.sh/uv/getting-started/installation/) -and ideally also, +Additionally, [the GitHub command line interface (CLI)](https://cli.github.com/), [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. -- [the GitHub command line interface (CLI)](https://cli.github.com/), -- [pre-commit](https://pre-commit.com/), -- [tox](https://tox.wiki). +An easy way to install the software you need is by using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below: -These additional three tools 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. - -An easy way to get all the software you need installed is using the tool [Conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) to create a dedicated environment with the necessary packages installed by following the step by step instructions below: - -1. Download and install [Miniconda](https://docs.anaconda.com/free/miniconda/) following the operating system specific instructions at either - - - for a graphical installer - - or for installation via the command line. - - If you already have Miniconda (or Anaconda) installed you can skip this step. - -2. Once Miniconda is installed, you need to open a terminal window: +1. Open a terminal window: - - On Windows: open the Start menu from the taskbar, type `miniconda` in the search field, then click `Anaconda Prompt (miniconda3)` from the results (or `Anaconda Prompt (anaconda3)` if using a previous Anaconda installation). + - On Windows: open the Start menu from the taskbar, type `cmd` in the search field, then click [command prompt](https://en.wikipedia.org/wiki/Command-line_interface#Command_prompt) from the results. - On MacOS: click the Launchpad icon in the Dock, type `Terminal` in the search field, then click `Terminal` from the results. - On Linux: open the default terminal application installed in your distribution. -3. Once you have a terminal window open you should see text `(base)` as part of your [command prompt](https://en.wikipedia.org/wiki/Command-line_interface#Command_prompt) if Minconda has been installed and set up correctly, indicating you currently have the default `base` environment active. If this is the case you should run +2. In the opened terminal window, use: ```sh - conda create -y -n python-tooling -c conda-forge cookiecutter git gh pre-commit tox + uv tool install cookiecutter gh pre-commit tox ``` - to create a new environment named `python-tooling` in to which will be installed the packages necessary for creating and using a package using the `UCL-ARC/python-tooling` cookiecutter template. + to install the "tools" necessary for creating and using a package using the `UCL-ARC/python-tooling` cookiecutter template. -4. To check that all the dependencies have installed correctly in the new environment first activate the environment by running - - ```sh - conda activate python-tooling - ``` - - at which point you should see `(base)` in the command prompt change to `(python-tooling)`, Then try running each of the following commands in turn, one at a time, +3. To check that all the dependencies have installed correctly, run each of the following commands in turn, one at a time, ```sh cookiecutter --version @@ -63,10 +44,10 @@ An easy way to get all the software you need installed is using the tool [Conda] For each command you should see some text outputted to the terminal giving details of the installed versions of the applications - the output itself is not important as long as you do not see any error messages. -5. If you also want to try out creating a GitHub repository for the package you will need to [sign-up for a free GitHub account](https://github.com/join) if you don't already have one. Once you have a GitHub account, open a terminal window - you can either use the same one as previously if you still have it open, or open a new terminal window as described in step 2 and then activate the `python-tooling` Conda environment by running +4. If you also want to try out creating a GitHub repository for the package you will need to [sign-up for a free GitHub account](https://github.com/join) if you don't already have one. Once you have a GitHub account, open a terminal window - you can either use the same one as previously if you still have it open, or open a new terminal window as described in step 2 and then activate the `python-tooling` Conda environment by running ```sh - conda activate python-tooling + source .venv/bin/activate ``` Once you have a terminal window with the `python-tooling` environment active (you should see `(python-tooling)` in your command prompt) run @@ -90,22 +71,13 @@ An easy way to get all the software you need installed is using the tool [Conda] We will first go through the steps for creating a new package using the `UCL-ARC/python-tooling` cookiecutter template. -1. Open a terminal window: - - - On Windows: open the Start menu from the taskbar, type `miniconda` in the search field, then click `Anaconda Prompt (miniconda3)` from the results. - - On MacOS: click the Launchpad icon in the Dock, type `Terminal` in the search field, then click `Terminal` from the results. - - On Linux: open the default terminal application installed in your distribution. - -2. In the opened terminal window change the working directory to the path you wish to create the package in using the `cd` (change directory) command. -3. Activate the `python-tooling` Conda environment you previously created ([see instructions above](#%EF%B8%8F-setting-up-dependencies-for-using-template)) by running +1. Open a new terminal/command prompt window and change the working directory to the path you wish to create the package in using the `cd` (change directory) command. ```sh - conda activate python-tooling + cd path/to/directory ``` - You should now see the text `(python-tooling)` in your [command prompt](https://en.wikipedia.org/wiki/Command-line_interface#Command_prompt). If you installed, or already had installed, the tools listed above in the set up instructions at a system level you can skip this step. - -4. To begin creating the package run +2. To begin creating the package run ```sh cookiecutter gh:ucl-arc/python-tooling --checkout latest @@ -113,7 +85,7 @@ We will first go through the steps for creating a new package using the `UCL-ARC You will then be shown a series of prompts at the command line asking for details of the project and package. You can choose to use the default placeholder value (shown in parenthesis `()` in prompt) for any question by hitting `Enter`. If you already have a specific project in mind you want to set up a package for using the template you can use this project's details, otherwise you can just use the placeholder values. You should choose `Y` (yes) to the questions on whether to initialise Git repository and automatically deploy HTML documentation to GitHub Pages to allow you to complete the follow on exercises which rely on these options being enabled. For the prompt asking for the GitHub user or organization name to be owner of repository you should supply your GitHub user name. -5. Once you have completed all the cookiecutter prompts some additional instructions will be printed to screen (which we will come back to in the next sections) and your new package will be generated in a directory named `{project_slug}` in the current working directory (where `{project_slug}` is the value entered for the `'Slugified' project name...`[^slug] prompt, this will be `python-template` if you used the default placeholder values). You can see the directory tree of files generated by running (if on Linux or MacOS) +3. Once you have completed all the cookiecutter prompts some additional instructions will be printed to screen (which we will come back to in the next sections) and your new package will be generated in a directory named `{project_slug}` in the current working directory (where `{project_slug}` is the value entered for the `'Slugified' project name...`[^slug] prompt, this will be `python-template` if you used the default placeholder values). You can see the directory tree of files generated by running (if on Linux or MacOS) ```sh tree {project_slug} @@ -223,25 +195,41 @@ The index page of the documentation reproduces the content from the repository R ## ๐Ÿ Setting up a virtual environment for project -Whenever you are working on a Python project we would recommend setting up a project-specific [virtual environment](https://docs.python.org/3/tutorial/venv.html). This allows you to install the versions of third-party packages the project requires without conflicting with the requirements of other projects you are developing. +It is recommended to set up a project-specific [virtual environment](https://docs.python.org/3/tutorial/venv.html) whenever working on Python project. This allows you to install the versions of third-party packages the project requires without conflicting with the requirements of other projects you are developing. + +There are a variety of virtual environment management tools available for Python. One option is [uv](https://docs.astral.sh/uv), which you will have installed if you followed our detailed set-up instructions above, or may already have installed previously. `uv` is an extremely fast Python package and virtual environment manager that has API compatiblility with `pip` and the built-in virtual environment manager - [`venv`](https://docs.python.org/3/library/venv.html). -There are a variety of virtual environment management tools available for Python. One option is [Conda](https://conda.io/projects/conda/en/latest/index.html), which you will have installed if you followed our detailed set-up instructions above, or may already have installed previously. Conda can install both Python packages and other tools - for example in the set-up instructions we recommended using it to install Git. Compared to other Python virtual environment options, Conda has the advantage that it can also be used to install different versions of Python itself, which can be useful to set up environments to test across multiple Python versions rather than having to use the Python versions installed at a system level or using a separate tool like [pyenv](https://github.com/pyenv/pyenv) to manage multiple Python versions. +A virtual environment for the project can be created by running the following in a terminal/command prompt window + +```sh +uv venv .venv +``` -A Conda environment for the project can be created by running in a terminal the command +This will create a new environment with name `.venv`, which can be activated for installing packages using ```sh -conda create -y -n {project_slug} -c conda-forge python +source .venv/bin/activate ``` -This will create a new environment with name `{project_slug}` (which you should replace with the relevant project slug value for your project), installing the latest version of Python using the package hosted on the [community driven `conda-forge` channel](https://conda-forge.org/). To make this Conda environment the current active environment run +or if on Windows ```sh -conda activate {project_slug} +.venv\Scripts\activate ``` -again replacing `{project_slug}` with the relevant project slug for your package. +Once you have activated the environment you can use the following command to install any packages within the `.venv` environment + +```sh +uv pip install numpy +``` + +You can even use an arbitrary Python version to create `uv` environments, and `uv` will fetch that Python version if it is not available locally + +```sh +uv venv --python 3.11.6 +``` -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, has less features, and is not developed rapidly when compared to `uv`, but is built-in to the Python standard library. Similar to `uv`, a virtual environment can be created using ```sh python -m venv .venv From ba7ecb1e1415797998a5d26b4d661e3f7ce72aa0 Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Tue, 11 Feb 2025 21:47:48 +0000 Subject: [PATCH 02/11] uniform punctuations --- tutorial.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tutorial.md b/tutorial.md index d353d99d..2439b73b 100644 --- a/tutorial.md +++ b/tutorial.md @@ -9,22 +9,22 @@ In this tutorial we will go through in detail the steps required to set-up a Pyt
Click to expand... -To start using the template you will need at least the following software tools installed: +To use the template you will need at least the following software tools installed - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - [uv](https://docs.astral.sh/uv/getting-started/installation/) Additionally, [the GitHub command line interface (CLI)](https://cli.github.com/), [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. -An easy way to install the software you need is by using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below: +An easy way to install the software you need is by using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below -1. Open a terminal window: +1. Open a terminal window - On Windows: open the Start menu from the taskbar, type `cmd` in the search field, then click [command prompt](https://en.wikipedia.org/wiki/Command-line_interface#Command_prompt) from the results. - On MacOS: click the Launchpad icon in the Dock, type `Terminal` in the search field, then click `Terminal` from the results. - On Linux: open the default terminal application installed in your distribution. -2. In the opened terminal window, use: +2. In the terminal window, use ```sh uv tool install cookiecutter gh pre-commit tox @@ -32,7 +32,7 @@ An easy way to install the software you need is by using `uv`, which can create to install the "tools" necessary for creating and using a package using the `UCL-ARC/python-tooling` cookiecutter template. -3. To check that all the dependencies have installed correctly, run each of the following commands in turn, one at a time, +3. To check that all the dependencies have installed correctly, run each of the following commands in turn, one at a time ```sh cookiecutter --version @@ -71,7 +71,7 @@ An easy way to install the software you need is by using `uv`, which can create We will first go through the steps for creating a new package using the `UCL-ARC/python-tooling` cookiecutter template. -1. Open a new terminal/command prompt window and change the working directory to the path you wish to create the package in using the `cd` (change directory) command. +1. Open a new terminal/command prompt window and change the working directory to the path you wish to create the package in using the `cd` (change directory) command ```sh cd path/to/directory From 2c8529992a1455f563820d8201857734c969472d Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Wed, 12 Feb 2025 11:12:50 +0000 Subject: [PATCH 03/11] update gh installation instruction --- tutorial.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/tutorial.md b/tutorial.md index 2439b73b..248f1e18 100644 --- a/tutorial.md +++ b/tutorial.md @@ -13,8 +13,9 @@ To use the template you will need at least the following software tools installe - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - [uv](https://docs.astral.sh/uv/getting-started/installation/) +- [the GitHub command line interface (CLI)](https://github.com/cli/cli?tab=readme-ov-file#installation) -Additionally, [the GitHub command line interface (CLI)](https://cli.github.com/), [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 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. An easy way to install the software you need is by using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below @@ -27,7 +28,9 @@ An easy way to install the software you need is by using `uv`, which can create 2. In the terminal window, use ```sh - uv tool install cookiecutter gh pre-commit tox + uv tool install cookiecutter + uv tool install pre-commit + uv tool install tox ``` to install the "tools" necessary for creating and using a package using the `UCL-ARC/python-tooling` cookiecutter template. @@ -44,13 +47,7 @@ An easy way to install the software you need is by using `uv`, which can create For each command you should see some text outputted to the terminal giving details of the installed versions of the applications - the output itself is not important as long as you do not see any error messages. -4. If you also want to try out creating a GitHub repository for the package you will need to [sign-up for a free GitHub account](https://github.com/join) if you don't already have one. Once you have a GitHub account, open a terminal window - you can either use the same one as previously if you still have it open, or open a new terminal window as described in step 2 and then activate the `python-tooling` Conda environment by running - - ```sh - source .venv/bin/activate - ``` - - Once you have a terminal window with the `python-tooling` environment active (you should see `(python-tooling)` in your command prompt) run +4. If you also want to try out creating a GitHub repository for the package you will need to [sign-up for a free GitHub account](https://github.com/join) if you don't already have one. Once you have a GitHub account, open a terminal window - you can either use the same one as previously if you still have it open, or open a new terminal window as described in step 2 and then run ```sh gh auth login @@ -199,7 +196,7 @@ It is recommended to set up a project-specific [virtual environment](https://doc There are a variety of virtual environment management tools available for Python. One option is [uv](https://docs.astral.sh/uv), which you will have installed if you followed our detailed set-up instructions above, or may already have installed previously. `uv` is an extremely fast Python package and virtual environment manager that has API compatiblility with `pip` and the built-in virtual environment manager - [`venv`](https://docs.python.org/3/library/venv.html). -A virtual environment for the project can be created by running the following in a terminal/command prompt window +Once you are in your `{project_slug}` directory, a virtual environment can be created by running the following in a terminal/command prompt window ```sh uv venv .venv @@ -217,12 +214,18 @@ or if on Windows .venv\Scripts\activate ``` -Once you have activated the environment you can use the following command to install any packages within the `.venv` environment +You should see `(.venv)` on the left of your terminal window. Once you have activated the environment you can use the following command to install any packages within the `.venv` environment ```sh uv pip install numpy ``` +The environment can be deactivated using + +```sh +deactivate +``` + You can even use an arbitrary Python version to create `uv` environments, and `uv` will fetch that Python version if it is not available locally ```sh From c9fcc84d23b3fbe74531877ba48b59999d72c1dd Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Wed, 12 Feb 2025 11:52:25 +0000 Subject: [PATCH 04/11] fixes for windows --- tutorial.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/tutorial.md b/tutorial.md index 248f1e18..73377d6c 100644 --- a/tutorial.md +++ b/tutorial.md @@ -82,7 +82,7 @@ We will first go through the steps for creating a new package using the `UCL-ARC You will then be shown a series of prompts at the command line asking for details of the project and package. You can choose to use the default placeholder value (shown in parenthesis `()` in prompt) for any question by hitting `Enter`. If you already have a specific project in mind you want to set up a package for using the template you can use this project's details, otherwise you can just use the placeholder values. You should choose `Y` (yes) to the questions on whether to initialise Git repository and automatically deploy HTML documentation to GitHub Pages to allow you to complete the follow on exercises which rely on these options being enabled. For the prompt asking for the GitHub user or organization name to be owner of repository you should supply your GitHub user name. -3. Once you have completed all the cookiecutter prompts some additional instructions will be printed to screen (which we will come back to in the next sections) and your new package will be generated in a directory named `{project_slug}` in the current working directory (where `{project_slug}` is the value entered for the `'Slugified' project name...`[^slug] prompt, this will be `python-template` if you used the default placeholder values). You can see the directory tree of files generated by running (if on Linux or MacOS) +3. Once you have completed all the cookiecutter prompts some additional instructions will be printed to screen (which we will come back to in the next sections) and your new package will be generated in a directory named `{project_slug}` in the current working directory (where `{project_slug}` is the value entered for the `'Slugified' project name...`[^slug] prompt, this will be `python-template` if you used the default placeholder values). You can see the directory tree of files generated by running ```sh tree {project_slug} @@ -109,7 +109,13 @@ We will first go through the steps for creating a new package using the `UCL-ARC cat {path_to_file} ``` - replacing `{path_to_file}` with the relevant path. + on macOS/Linux or + + ```sh + type {path_to_file} + ``` + + on Windows, replacing `{path_to_file}` with the relevant path. [^slug]: A ['slug'](https://en.wikipedia.org/wiki/Clean_URL#Slug) in this context is a human readable identifier with words typically separated by hyphens that can be used as part of a URL. From 1a0449f4273a64ce8656405e78ac7d91cb999b53 Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Wed, 12 Feb 2025 14:36:05 +0000 Subject: [PATCH 05/11] language Co-authored-by: Patrick J. Roddy --- tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorial.md b/tutorial.md index 73377d6c..ee20f1b7 100644 --- a/tutorial.md +++ b/tutorial.md @@ -25,7 +25,7 @@ An easy way to install the software you need is by using `uv`, which can create - On MacOS: click the Launchpad icon in the Dock, type `Terminal` in the search field, then click `Terminal` from the results. - On Linux: open the default terminal application installed in your distribution. -2. In the terminal window, use +2. In the terminal window, type ```sh uv tool install cookiecutter @@ -238,7 +238,7 @@ You can even use an arbitrary Python version to create `uv` environments, and `u uv venv --python 3.11.6 ``` -Alternatively, you can use the [`venv` module](https://docs.python.org/3/library/venv.html), which is slower, has less features, and is not developed rapidly when compared to `uv`, but is built-in to the Python standard library. Similar to `uv`, a virtual environment can be created using +Alternatively, you can use the [`venv` module](https://docs.python.org/3/library/venv.html), which is slower, has fewer features, and is not developed rapidly when compared to `uv`, but is built-in to the Python standard library. Similar to `uv`, a virtual environment can be created using ```sh python -m venv .venv From aef4cac24598748158071f4989f3a4febc8be1a7 Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Wed, 12 Feb 2025 14:41:56 +0000 Subject: [PATCH 06/11] we do not need tox and pre-commit --- tutorial.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/tutorial.md b/tutorial.md index ee20f1b7..b1ba32c1 100644 --- a/tutorial.md +++ b/tutorial.md @@ -15,9 +15,9 @@ To use the template you will need at least the following software tools installe - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [the GitHub command line interface (CLI)](https://github.com/cli/cli?tab=readme-ov-file#installation) -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, [cookiecutter](https://cookiecutter.readthedocs.io) will be required to generate your package from them template, which can be installed using the instructions below. 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. -An easy way to install the software you need is by using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below +An easy way to install and manage Python packages is using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below 1. Open a terminal window @@ -29,8 +29,6 @@ An easy way to install the software you need is by using `uv`, which can create ```sh uv tool install cookiecutter - uv tool install pre-commit - uv tool install tox ``` to install the "tools" necessary for creating and using a package using the `UCL-ARC/python-tooling` cookiecutter template. @@ -41,8 +39,6 @@ An easy way to install the software you need is by using `uv`, which can create cookiecutter --version gh --version git --version - pre-commit --version - tox --version ``` For each command you should see some text outputted to the terminal giving details of the installed versions of the applications - the output itself is not important as long as you do not see any error messages. @@ -238,7 +234,7 @@ You can even use an arbitrary Python version to create `uv` environments, and `u uv venv --python 3.11.6 ``` -Alternatively, you can use the [`venv` module](https://docs.python.org/3/library/venv.html), which is slower, has fewer features, and is not developed rapidly when compared to `uv`, but is built-in to the Python standard library. Similar to `uv`, a virtual environment can be created using +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 ```sh python -m venv .venv From 072d437d471b942cbb9e1ab7227d5d82bc0adf1d Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Wed, 12 Feb 2025 14:48:43 +0000 Subject: [PATCH 07/11] more explicit about installation --- tutorial.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tutorial.md b/tutorial.md index b1ba32c1..12f0e456 100644 --- a/tutorial.md +++ b/tutorial.md @@ -9,12 +9,14 @@ In this tutorial we will go through in detail the steps required to set-up a Pyt
Click to expand... -To use the template you will need at least the following software tools installed +To use the template you will need to install the following software tools - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - [the GitHub command line interface (CLI)](https://github.com/cli/cli?tab=readme-ov-file#installation) +The instructions for installing these tools can be accessed by clicking the individual links above. + Additionally, [cookiecutter](https://cookiecutter.readthedocs.io) will be required to generate your package from them template, which can be installed using the instructions below. 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. An easy way to install and manage Python packages is using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below From 1c19d0e5f8b6684312633bab4b45fc64fc57ab36 Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Wed, 12 Feb 2025 14:50:22 +0000 Subject: [PATCH 08/11] them -> the --- tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial.md b/tutorial.md index 12f0e456..e06a1043 100644 --- a/tutorial.md +++ b/tutorial.md @@ -17,7 +17,7 @@ To use the template you will need to install the following software tools The instructions for installing these tools can be accessed by clicking the individual links above. -Additionally, [cookiecutter](https://cookiecutter.readthedocs.io) will be required to generate your package from them template, which can be installed using the instructions below. 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, [cookiecutter](https://cookiecutter.readthedocs.io) will be required to generate your package from the template, which can be installed using the instructions below. 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. An easy way to install and manage Python packages is using `uv`, which can create a dedicated environment with the necessary packages installed using the step by step instructions below From 5532011cb8837d1be78f8e89003e049fc6bbbc5a Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Thu, 13 Feb 2025 11:32:32 +0000 Subject: [PATCH 09/11] better distinction between venv and uv --- tutorial.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/tutorial.md b/tutorial.md index e06a1043..9be2a129 100644 --- a/tutorial.md +++ b/tutorial.md @@ -236,6 +236,8 @@ You can even use an arbitrary Python version to create `uv` environments, and `u uv venv --python 3.11.6 ``` +
Click to expand... + 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 ```sh @@ -266,6 +268,14 @@ Once you have created and activated a virtual environment for the project, you c python -m pip install --editable ".[dev,docs,test]" ``` +
+ +Once you have created and activated a virtual environment for the project, you can install the package in [editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), along with both its required dependencies and optional sets of dependencies for development (`dev`), documentation (`docs`) and testing (`test`) by running + +```sh +uv pip install --editable ".[dev,docs,test]" +``` + from the root of the project repository. ## ๐Ÿงช Running package tests locally From 5823dd0e6c65318b42120b86ca89ffcf5d7d064b Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Thu, 13 Feb 2025 11:34:06 +0000 Subject: [PATCH 10/11] better summary --- tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial.md b/tutorial.md index 9be2a129..c459280e 100644 --- a/tutorial.md +++ b/tutorial.md @@ -236,7 +236,7 @@ You can even use an arbitrary Python version to create `uv` environments, and `u uv venv --python 3.11.6 ``` -
Click to expand... +
Using `venv` as an alternative to `uv` 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 From 21ae8da2c58dce48085f8d906df7415d3c49dc7c Mon Sep 17 00:00:00 2001 From: Saransh Chopra Date: Thu, 13 Feb 2025 11:36:20 +0000 Subject: [PATCH 11/11] rearrage text --- tutorial.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/tutorial.md b/tutorial.md index c459280e..89a5bb89 100644 --- a/tutorial.md +++ b/tutorial.md @@ -236,7 +236,15 @@ You can even use an arbitrary Python version to create `uv` environments, and `u uv venv --python 3.11.6 ``` -
Using `venv` as an alternative to `uv` +Once you have created and activated a virtual environment for the project, you can install the package in [editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), along with both its required dependencies and optional sets of dependencies for development (`dev`), documentation (`docs`) and testing (`test`) by running + +```sh +uv pip install --editable ".[dev,docs,test]" +``` + +from the root of the project repository. + +
Using venv as an alternative to uv 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 @@ -262,7 +270,7 @@ Once you have activated the environment you should make sure the version of the python -m pip install --upgrade pip ``` -Once you have created and activated a virtual environment for the project, you can install the package in [editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), along with both its required dependencies and optional sets of dependencies for development (`dev`), documentation (`docs`) and testing (`test`) by running +Similar to `uv`, once the the environment is active, you can install the package in editable mode, along with both its required dependencies and optional sets of dependencies by running ```sh python -m pip install --editable ".[dev,docs,test]" @@ -270,14 +278,6 @@ python -m pip install --editable ".[dev,docs,test]"
-Once you have created and activated a virtual environment for the project, you can install the package in [editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), along with both its required dependencies and optional sets of dependencies for development (`dev`), documentation (`docs`) and testing (`test`) by running - -```sh -uv pip install --editable ".[dev,docs,test]" -``` - -from the root of the project repository. - ## ๐Ÿงช Running package tests locally The package template includes support for running tests using the [`pytest` testing framework](https://docs.pytest.org/). Tests are defined in modules in the `tests` directory. By default a single test module `tests/test_dummy.py` is created with a placeholder test. You can run the test locally using `pytest` directly (you will need to have the virtual environment active in which you installed the package and its dependencies) by running