What Is Poetry?
Poetry is a package and dependency manager for Python. It’s a replacement for the default dependency manager, pip, as well as the packaging tools. It has a lot of advantages, makes things much simpler and it's definitely worth using.
Why Would I Use It?
Python’s default package and dependency manager, pip, is, how can I put it, "acceptable". It has evolved with the language, and lets you specify dependencies in text files; e.g.: requirements.txt, requirements-dev.txt etc. You can then install and update these packages in your virtual environments, which you've created separately (or maybe with PyCharm). When it comes to publishing to PyPI, there are other tools that let you do that too.
Alternatively you can do all of this with Poetry, as well as using it to:
- - create new outline projects (with
poetry new) and upgrading new projects to use poetry (withpoetry init) - - create and activate virtual environments (with
poetry shell) - - build and package your projects into a wheel or sdist file (with
poetry build) - - publish your project to PyPI (
poetry publish) - full instructions on how do do this are at: How To Use Poetry to Publish a Python Package on PyPI - - display your project’s dependency tree
Given the choice of doing all of this with the tools that come with Python, or a single tool that does all of this, why wouldn’t you want to use that instead?
When Should I Use Poetry?
Poetry is a great system to use for any Python project. You can use it on existing projects as well as new projects, so if you’re using pip at the moment you can move to Poetry quite easily.
Once you’ve been using Python for a while, you’ll start to notice there are places where pip, and the other Python utilities, have a few “gaps” that Poetry fills very well.
How Do I Get Started?
Follow the Poetry download and installation instructions. Make sure you use the recommended method to download and install it. Don’t use any of the other methods – I’ve never managed to get everything working when I’ve done that. If you're using PyCharm, it now has built-in support for Poetry.
What Else Do I Need To Know?
There are some peculiarities with Poetry. Two that I’ve found are:
Version Pinning
If you’re using pip and one of your dependencies specifies a dependency of its own, without actually specifying a version, the latest version of this second level dependency will be downloaded. This might not be what you want.
You can prevent this from happening by specifying the second level dependency with a version in your own requirements.txt file. If you want to know a little more about this, there's more detail in Specify Your Dependency Versions.
Unfortunately, if you try this with Poetry it won’t work – it just downloads the latest version that fits all of the requirements, which is still the latest version of the second level dependency.
Unicode Error
On some versions of Ubuntu, with some versions of Python, and some versions of Poetry, you will get the following error:
UnicodeEncodeError
‘latin-1’ codec can’t encode character ‘\u2022’ in position 2: ordinal not in range(256)
at ~/.poetry/lib/poetry/_vendor/py3.6/clikit/io/output_stream/stream_output_stream.py:24 in write
This is caused by a localization error and can be fixed, at least until you upgrade Ubuntu, Python and/or Poetry, by calling Poetry as follows:
LC_ALL=C.UTF-8 ~/.poetry/bin/poetry
In short, this forces the system to use byte compatibility and byte-ordered sorting. It’s rather more complex than just that, but trust me, it works
