1. Setting up the environment

This lesson is an onboarding to get your computer ready before we start. It is designed for Windows. It does not count as a class lesson: you follow it at home and you arrive in the classroom with everything working.

Don't rush. Half of the problems people carry for an entire course come from a poorly set up environment on day one.

Installing the tools

We are going to install two things: uv and Python.

uv is the tool that ties everything together. It installs Python for you and manages the project's dependencies without you having to fight with versions. If you come from installing Python by hand from the website, forget that path: with uv it is faster and gives fewer problems.

Once uv is installed, Python is installed with a single command, without downloading anything from the Python website:

uv python install

When you are done, check that it responds:

uv --version

If it returns a version number, you are on the right track.

Starting a project

With the tools in place, creating a project is a matter of seconds:

uv init metocean-tools
cd metocean-tools

uv init creates the basic structure and the pyproject.toml (the project's dependency list).

Then we create and activate the virtual environment:

uv venv
.venv\Scripts\activate

A virtual environment is a folder that isolates this project's dependencies from the rest of the system. This way, if one project needs one version of a library and another needs a different one, they don't clash.

And we add dependencies when we need them. For example, a library to validate input data:

uv add msgspec

uv add downloads the library and records the exact version in pyproject.toml. That detail is gold: it means a colleague can copy your project and reproduce it without those weird "works on my machine" errors.

Configuring VSCode for Python

We recommend VSCode as the editor. It is one of the most used ones, so if you get stuck it is easier to find someone to lend you a hand. Now that you have the project created, open it in the editor (File > Open Folder and pick metocean-tools) and let's fine-tune it, because out of the box it comes fairly bare for Python.

Several of the steps that follow use the command palette, which is the editor's remote control: you open it with Ctrl+Shift+P (or with F1), type the name of an action and run it. If you prefer, type > in the search bar at the top and you get to the same place.

• Install the official Python extension (from Microsoft) and Pylance, which gives you autocompletion and code intelligence.
• Install the Ruff extension, which warns you of problems and formats the code. It reads the configuration from the project's pyproject.toml, so the whole team formats the same way.
• Select the correct interpreter: open the command palette, search for Python: Select Interpreter and choose the one from the .venv virtual environment you just created (it shows up as .venv or Python 3.x ('.venv')). The extension usually detects it on its own as soon as you open the project folder, but it is good to know how to do it by hand.
• Enable format on save: the quick way is to open the settings with Ctrl+,, search for Format On Save and tick the box. But for Ruff to be the Python formatter and for the whole team to have it the same way, it is best to write it in the project's .vscode/settings.json, which I show you right at the end of this section.
• Configure the test panel (Test Explorer): search for Python: Configure Tests and choose pytest. You don't have tests or pytest installed yet (they arrive in the testing lesson), so for now this is just leaving it ready: as soon as you have them, you can run and debug the tests from the sidebar with one click.
• Get familiar with the debugger: set a breakpoint (a click in the left margin, next to the line number) and step through it. It is far more useful than filling the code with print, and we will see it in detail later, in the testing lesson.

All of this configuration is shared with the team through the project's .vscode/settings.json file. Create it with this content and everyone starts the same way:

{
    "editor.formatOnSave": true,
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.codeActionsOnSave": {
            "source.organizeImports.ruff": "explicit"
        }
    }
}

With that, every time you save a Python file, Ruff formats it and sorts the imports for you, without you having to remember. charliermarsh.ruff is the identifier of the Ruff extension: it tells VSCode which formatter to use.

And with this the environment is ready. In the next lesson we recover this same project and use it as a starting point, without installing anything again.