Hello Python Developers!
In this blogpost, I am going to discuss one of the newer Python dependency management and packaging tools, Poetry.
Poetry first started to make an appearance in 2018, and since then has become exponentially more popular! Before Poetry, Python developers tended to use Pip or Conda, which are great tools, but do have their problems. For example, building a Python package in Pip is not a straightforward task, and upgrading dependencies can put you into a dependency hell with Pip since it might upgrade dependencies that do not work with other dependencies that you might have. Newer versions of Pip do adjust the dependency hell with resolvers, but it is still difficult to avoid at times.
Poetry came along and has made everything easier! For example, it will verify that nothing breaks with updates/upgrades prior to updating/upgrading, it is easier than ever to configure a Python package and publish it to a repository, such as Google Cloud Platform’s Artifact Repository, and it can do much more!
The goal of this blogpost is to give you a brief glimpse of Poetry, give you a basic understanding of some of the Poetry commands, and be able to do the following:
- Install Poetry
- Create a Python package/file setup that can utilize Poetry
- Create a Python virtual environment based off of a
.tomlfile - Update the Python dependencies with non-breaking updates
- Add/Remove Packages to your Poetry Project
This is only a quick run through of Poetry, it can do much more, in future blogposts, I will discuss more Poetry concepts.
Let’s dive in!
*** Note, this blogpost was prepared while utilizing a zsh terminal on a MacOS computer.
Install Poetry
This will be the simplest task, as Poetry has made it very easy for us. On a CURL-capable computer, make the following request:
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -After it is finished installing, open a new terminal and execute the following Poetry command to confirm successful installation: poetry --version .
*** At the time of writing this I am running 1.2.0b3
Create a Python Package/File setup that can utilize Poetry
Poetry gives you a command to generate a basic Python Poetry package, which is poetry new <package-name> .
This will give you the following folder structure:
- <package-name>/
This contains an __init__.py file similar to normal non-Poetry Python packages and has the same functionality/purpose.
- tests/
This also contains an __init__.py file similar to normal non-Poetry Python packages and has the same functionality/purpose.
- pyproject.toml
This is a unique filetype that Poetry utilizes. toml stands for: Tom’s Obvious Minimal Language and as it’s creators describe it:
TOML aims to be a minimal configuration file format that’s easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.
This is the main Poetry file, and it is responsible for telling your project which dependencies need to be installed.
This is all of the files that are produced by the poetry new command, but you will also encounter another file more often than not: poetry.lock . This file is created after your initial installation or after you run an update (will discuss later in this post) and it holds the exact versions that you are using for your dependencies. You want to push this file to version control, as it will give other developers working on the repo, the same dependencies as you.
Create a Python Virtual Environment based off of a .toml file
We now have our Python Poetry project, how do we generate a virtual environment with or without a poetry.lock file?
You will simply run poetry install !
If you do not have a poetry.lock file, it will install everything listed in the pyproject.toml file as the latest version for the inputted package version value (for example ^2.0.0 will not get 3.0.0, but will get 2.1.0 or 2.0.1, etc…).
If you do have a poetry.lock file, it will install the exact versions that are listed in the lock file.
Update the Python Dependencies with Non-Breaking Updates
You are tasked to update your all of your non-breaking dependencies updates in your Poetry project. How do you do this?
You simple run poetry update and all of the dependencies will update to the latest version that is not a major version update, and if dependencies collide, you will be alerted.
*** You will need to include a ^, ~, etc… in the version in the pyproject.toml file in order for it to update.
Add/Remove Packages to your Poetry Project
Similar to pip this is a very easy command. You will run the following to add a package to your pyproject.toml and poetry.lock (if it exists) files: poetry add <package-name> .
Also to remove a package and its dependencies, you will execute the following command: poetry remove <package-name> .
Conclusion
This was a brief run through of the Python Poetry Packaging and Dependency Management tool. I hope it was helpful for you, and helps urge you to give Poetry a try!
In the near future, I will add a blogpost or two regarding package building/publishing with Poetry, more thorough explanations of other Poetry commands, build off of the concepts presented here, and an easy to follow walkthrough.
Thank you for the read, Happy Coding!
