Contents

Level 2: Use Poetry and Python virtual environments

Level 2: Use Poetry and Python virtual environments

Poetry has a few advantages:

  • It assembles information about the project in a single pyproject.toml file

  • It manages dependencies and has a constraint solver for the dependency versions.

  • It updates, installs, removes dependencies from the virtual environment linked to the project.

Before you install Poetry, be sure to read Python versions.

Install Poetry

Poetry is a self-contained command-line tool. Follow the instructions at https://python-poetry.org/docs/#installation. There should not be surprises.

Prepare the project environment with python -m venv .venv

In your project folder, run python -m venv .venv to create a virtual environment in a .venv subfolder. This subfolder will be recognized both by Poetry and VS Code when looking for environments.

You can set virtualenvs.in-project to true to perform this step automatically. Run in the shell:

poetry config virtualenvs.in-project true

Initialize the Poetry configuration

In your project folder, run poetry init, which will interactively ask you basic information about your project.

Then run poetry update to resolve dependencies and create or update the poetry.lock file.

The command poetry install, on the other hand, installs/removes Python dependencies in the virtual environment so that they match exactly what is specified in the poetry.lock file.

Should you distribute the poetry.lock files to users, or should you avoid storing it in the Git repository (using .gitignore)?

  • If you are writing a Python library that will be integrated in other projects, do not distribute the poetry.lock file; instead, add it to .gitignore.

  • If your users will run your code directly, do distribute the poetry.lock file so that their virtual environment will match exactly yours.

To run things in the proper virtual environment

VS Code will normally run/debug code and open terminals in the .venv Poetry-managed virtual environment. If you are running things from the command-line, either do:

  • Type poetry shell to drop in a shell with the virtual environment activated

  • Type poetry run ipython myscript.py or poetry run mypy, …, to run commands inside the virtual environment.

Folder structure

I use the following folder structure. See configpile for an example.

  • .github/workflows contains the trigger that builds the documentation website.

  • .vscode contains the VS Code settings specific to the project.

  • docs is the Sphinx documentation folder, with docs/Makefile enabling the documentation build

  • docs/source contains the Sphinx source, including conf.py

  • src/PROJECTNAME contains the module source code.

    It is good practice to put the project under a src subfolder. Do not worry: Python will find your package source files when importing it because poetry install writes a special .pth file in the site-packages of your virtual environment.

  • tests for unit tests, will be discovered automatically by VS Code and pytest

Python modules

I recommend keeping your source files < 1000 lines of code long.