Repository files navigation

Poetry is modestly described byits official documentation as adependency management tool, but it is in fact emerging as a de facto standard^†) to

^{[†]: QuotingHow to manage Python projects with Poetry}

• control virtual environments

• create and publish packages/libraries

• quickly set up new Python projects (or to easily convert existing ones)

Even though the Python eco-system is rich with internal (venv,pyvenv) and external tools (pip,pyenv,pipenv,virtualenv, etc.) that take on one or two of the roles listed above, this diversity can become an issue:

• differing conventions and proliferating command line options incur some cognitive overhead

• one has to carefully choosewhich tools to use together

• not all such projects run on every operating system (e.g.,pyenv does not support Windows directly)

Poetry aims to consolidate the functionality of all these tools (TODO: paraphrase,https://www.software.com/src/poetry-can-redefine-the-future-of-python), while striving to stay easy to use and configure.

^{[†]: ParaphrasingIs Poetry the future of Python?}

Nix is across-platform system package manager supported on most major distributions of Unix derivative operating systems (Linux, BSDs, MacOS, etc.) but it is not available on Windows.

^{The title of the section is deliberately not called "Installation" also because the"Installation" section of thePoetry documentation comprehensively covers this topic for operating systemsnot managed withNix (the reason I elected to demonstrate usingPoetry withNix in the first place), and becauseNix allows using software (and software components) in a way that doesn't conform to the traditional use of the term "installation".}

$ nix-shell -p python3 poetry

nix-shell will start a sub-shell with the latest Python 3 andPoetry executables, and one can start hacking.

NOTE: Once exiting the sub-shell,python3 andpoetry are still available on the system (seewhich poetry andwhich python3) but they are not referenced in thePATH environment variable. Hence they will need to be aliased or called by their full path. (Packages used withnix-shell are also subject togarbage collection after leaving the sub-shell.)

nix-shell can also be used to set up a more elaborate development environment, and this is probably the most flexible and convenient way.

ASIDE: The blog postDeveloping Python with Poetry &poetry2nix: reproducible flexible Python environments nicely expands on this topic.

$ nix-env -i python3 poetry

The only difference between with this one-liner and the one in the previous section is thatpython3 andpoetry are now available inPATH, and they won't be garbage collected (unless removed with [nix-env -e] first).

TODO:nix-env -i poetry fails witherror: selector 'poetry' matches no derivations; related to channels?

WARNING: This is a more advanced (and sprawling)Nix topic, and I still believe that the most convenient way is usingnix-shell, but it's mentioned here for completeness sake.

The following are the best places to start with, depending

• whether on NixOS:Chapter 6. Package Management in theNixOS manual

• or using Nix on other Unix derivatives:2.6. Declarative Package Management of theNixpkgs manual

Nix also offers a lot of freedom on how to do things, and this can complicate things, therefore the following resources are also suggested for reading:

• Part III. Package Management in theNix manual

• Declarative Configuration on the NixOS Wiki

• Declarative package management for normal users thread on NixOS Discourse

• Declarative approach to installing packages for user only on Reddit

• How do I do declarative package management using nix package manager on Debian? on Reddit

• Difference between nix profiles and home-manager on NixOS Discourse

• /etc/nixos/configuration.nix vs~/.config/nixpkgs/config.nix on Reddit

There are many "getting started" guides out there (e.g.,1,2,3,4,5,6), therefore I was striving to show (a hint of) the big picture.

WARNING: Please take any info in this section with grain of salt: put this together based on theofficial documentation, but I'm a new to Python, and it hasn't been reviewed by more experienced users at all.

The flowchart below shows howPoetry'sconfiguration options come into play when

• taking out your project for a spin (using commands such aspoetry shell,poetry run)

• making changes in configuration (e.g., withpoetry config), or most times

• managing the virtual environment (mostly when usingpoetry env).

The above flowchart may not convey clearly howPoetry chooses the virtual environment to use so this table is to provide an alternative representation: