Get and use the training source

PDM and UV?

PDM and UV are two very similar tools. They are both modern Python project managers.

• PDM is written in pure Python and closely follows the PyPA PEPs (see Introduction: PyPI and friends).

• UV is newer. It is written (in Rust) with a strong focus on speed (in particular using agressive caching).

Overall, these two tools are complementary.

For this training, we will mostly use UV (in Use, make & share Python software). However, in this page, we will use two PDM commands (pdm sync and pdm run) since the py-edu-fr project uses PDM. Note that UV also has very similar commands (uv sync and uv run).

Prerequisites

To get and use the repository of this training, one needs UV, Mercurial and PDM.

We explain in Preliminaries how UV and Mercurial can be installed:

• for UV, see Python,

• for Mercurial, see Versioning tools,

For PMD, just run

uv tool install pdm -p 3.13

You can then check the installations with

uv --version
hg --version
pdm --version

You should already have cloned the repository of this training (Clone the repo of this training). Now it is time to use it!

Exercise 2

Open a terminal and cd into the directory of the repository of the course.

If it is not yet cloned, you should use something like (potentially after a cd where/you/want/to/put/the/repo):

hg clone https://foss.heptapod.net/py-edu-fr/py-edu-fr
ls
cd py-edu-fr

You were not able to clone the repository for any reason?

You can just download an archive representing the last state of the project here: zip file or tar.gz file.

If it is already cloned, you can update the repo to be sure to have the last version of the source.

cd py-edu-fr
hg pull
hg up default

Note

If Mercurial tells you that you have modified files, you can run

hg up default --clean

Once the sources of the course are there and up-to-date, you should be able to use them:

Exercise 3

To create the virtual environment of the training, cd in the root directory of the training (py-edu-fr) and run

pdm sync

PDM should install a Python virtual environment in the directory py-edu-fr/.venv. Let us use the command ls .venv to see what is in this new directory.

sync, lock file and pyproject.toml

The sync command installs a virtual environment fully described in a lock file (here pdm.lock), which is usually versioned. The dependencies (third party Python packages) explicitly needed for the project are listed in the file pyproject.toml. The process to produce the lock file from the pyproject.toml file is called to “lock” the dependencies.

This also applies to other tools like UV, Pixi and Poetry.

We can now activate the environment to use it (i.e. to use the software installed in this environment):

Windows

.venv\Scripts\activate

macOS and Linux

source .venv/bin/activate

or just (in this case, the first . means source)

. .venv/bin/activate

After activation of the environment, the command python should correspond to the Python of the virtual environment. Let us check that with:

Windows

Get-Command python

macOS and Linux

which python

What is the output? Does it make sense?

Note that the virtual environment can also be used without activation. In a new terminal, cd in the root directory of the training and open a JupyterLab server with:

pdm run jupyter-lab

You should now have two terminals opened:

• one with the environment activated,

• one running a JupyterLab server.

You should now have:

• all the files used for this training:

  • examples and data in py-edu-fr/src/common

  • notebooks in py-edu-fr/src/en

• a virtual environment usable for the whole training (in py-edu-fr/.venv)

Exercise 4

In JupyterLab, navigate to the directory src/en/generalities. Note that there are .md files (text files containing Markdown code). However, these files can also be opened as notebooks. Right click on the file howto-use-python.md and choose “Open as notebook”.

Exercise 5

In the terminal with the environment activated, you can open the current directory with VSCode with:

code .
# or `codium .` if you use codium
# the `.` means the current directory

In VSCode, navigate to the directory src/common/examples and click on the file helloworld.py.

If you have the Python extension installed, the environment of the training should be detected and used automatically.