Project Maintenance with Poetry

One of the main features of poetry is that it makes dependency-management really convenient. Poetry works on the basis of the pyproject.toml file of this project, resolves the listed dependencies and creates a poetry.lock file (to guarantee that all people working on the project use the same dependency versions).

Bookmarks

• Poetry (Official Website)
  • Poetry Documentation
    • Poetry Installation
    • Basic Usage
    • Managing Dependencies (and dependency groups)
    • (CLI) Commands
  • Poetry Blog: Announcements of new releases
    • Poetry Release Notes

Optional, but recommended:

• pipx: install and run Python applications in isolated environments
• pyenv: simple Python version management
  • (use this tool to switch between different Python versions without accidentally overwriting your system's global python version)

Recommended Installation Settings

Please make sure that you followed the Poetry Installation Guide first and that your Poetry is up to date. Typing poetry --version into your console / terminal should produce a similar output:

$ poetry --version
Poetry (version 1.8.3)

If you are using pyCharm and want to have an easier experience while handling virtual environments (.venv/), you might want to set up poetry to create virtualenvs within the project's root directory. (oeh-search-etl is set up to .gitignore any .venv directories.)

Cheat Sheet: Frequently Used poetry Commands

After making sure that you have installed Poetry, you can use the following commands within your terminal to save some time in the future:

1. poetry check: checks if the pyproject.toml-structure is still valid
2. poetry install:
   1. reads the pyproject.toml-file
   2. installs dependencies
   3. and updates the poetry.lock-file
3. poetry show --tree: displays the dependencies in a tree-view
4. poetry show --outdated: shows outdated dependencies
   1. you can adjust the pyproject.toml file manually to version-pin specific dependencies
   2. or use the poetry add command with a version constraint,
      1. e.g. poetry add playwright==1.46.0 version-pins the playwright-package to v1.46.0
   3. now update the dependencies according to your pyproject.toml specifications:
      1. to update all dependencies, use poetry update
      2. or update individual packages only by using poetry update <package_name>
      3. (reminder: poetry update respects the version constraints of your pyproject.toml and will not update a version-pinned package above your defined version constraints!)
         1. If you want to update a package to a higher version than specified in your pyproject.toml file, use the above-mentioned poetry add command!
5. optional: save the requirements_dependencies_tree.txt-file for an (easier) visual overview
   1. poetry show --tree > requirements_dependencies_tree.txt