How-to Poetry

Poetry is a way to manage virtual environment in Python, a bit similar to Anaconda. The way it is being using in t-s is that there is a pyproject.toml file and a lock file in the root of the repo, which means you can just poetry install to create the virtualenv. By default, the “extras” dependencies will not be installed. To install those, you instaed need to do poetry install --extras "<name of package>"; this is equivalent to doing poetry install and on top of that installing the extra dependencies requested. When you update the version of certain dependencies, you can update you poetry environment by doing poetry install. To add new dependencies without modifying the pyproject.toml, you can do poetry add <name_of_dependency>.

Once you’re all set up, you can run some commands inside your virtual environment. For instance, to run ipython, you would do

poetry run ipython

To start a jupyter notebook session, you would do

poetry run jupyter-notebook

Their documentation is pretty good.

How to add a dependency

The first time you create a pyproject.toml file and you run poetry install, poetry will resolve all the conflicts and save the version of each dependency in a lock file, poetry.lock. You should version control both files.

If you want to add a new dependency, add it in the poetry.toml file then run poetry install, which will update the lock file and commit both.

Because poetry resolves conflicts for you, you will not necessarily have, in your lock file, the latest verison of all dependencies as requested in your pyproject.toml file. If you want to update your dependencies, you need to run poetry update, which will effectively delete your lock file and installing again.

Note that sometimes, adding directly into the pyproject.toml file doesn’t work (SolverProblemError…version solving failed) even though poetry should be able to find it. The workaround (which is a bug) is to install that dependency via poetry add <dependency>. This let poetry add that dependency to the .toml file then resolves conflicts in the .lock file.