What is new in poetry 1.2

New features and breaking changes in poetry

Photo by Manuel Nägeli on Unsplash

This article is a follow-up to this one, where I presented poetry 1.0.0. If you know nothing about poetry, starting there may be a good idea. So now, we will talk about the changes starting in version 1.2.

Installation

You need to have python3.7+ installed before trying to install poetry.

On Linux / Mac OS, you can run:

$ curl -sSL https://install.python-poetry.org | python3 -

On Windows, you can run:

> (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Note: On Windows, if you installed python through the Microsoft store, replace py with pythonin the last command.

To make sure poetry is installed, you can run the following command:

$ poetry --version
Poetry (version 1.2.2)

If you already have poetry installed, you can update it with the following command: poetry self update.

What’s new?

First, version 1.2 and upwards will no longer support Python 2.7 projects.

managing dependencies

To illustrate this change, we will consider working on a web scraping project. To initialize a project with poetry, you can use this command: poetry new scraper. Inside the scraper folder, let’s say we want to install httpx and parsel for the web scraping stuff, we will run this command:

$ poetry add httpx parsel

Note: I have a web scraping project, if you are curious, you can read an article I wrote on it here.

Once, we write some code, we want now to write tests, so we will use pytest and respx for this purpose. Previously, we would write something like poetry add -D pytext respxbut now we need to specify a group where non-main dependencies will be located. Let’s say, we call this group test, so to install these dependencies, we will type:

$ poetry add pytest respx --group test

The resulting pyproject.toml file will have the following sections (I paste only relevant sections, not the entire file):

[tool.poetry.dependencies]
python = "^3.7"
httpx = "^0.23.2"
parsel = "^1.7.0"


[tool.poetry.group.test.dependencies]
pytest = "^7.2.0"
respx = "^0.20.1"

This is probably the main feature poetry 1.2 brings. It allows you to fine-tune the organization of your dependencies. For example, let’s say we want to properly format our code, order imports, and check some basics PEP 8 errors, we will need packages like black, isort, and flake8. But these packages are not test packages, they can be summarized like lint packages, so we will add them to a lint group.

$ poetry add black isort flake8 --group lint

Also, let’s say, we want to document our project, we will add libraries like mkdocs + mkdocs-materials in new group docs.

$ poetry add mkdocs mkdocs-material --group docs

But this time, we will mark this group optional since it is used in a very specific case (take care of the first two lines of the following snippet)

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "^1.4.2"
mkdocs-material = "^9.0.0"

This is how we mark a group as optional. So when we will install a project with poetry installit will not install by default all optional groups like the docs one. If we want to install it, we will need to append a special instruction poetry install — with docs.

Also, if you only want to install the main dependencies, we can type poetry install --only main. With the same --only flag, we can choose which groups we only want to install by separating them with a comma, poetry install --only docs,test.

Finally, we can also choose to not install some group dependencies using the --withoutflag, i.e poetry install --without lint .

plugins

Poetry 1.2 now ships a system of plugins to alter or enhance the tool. To write a plugin, you can read this documentation. To use a plugin, you can type:

$ poetry self add poetry-plugin-<NAME>

To remove a plugin, you type:

$ poetry self remove poetry-plugin-<NAME>

To list your plugins, you type:

$ poetry self show plugins

  • poetry-plugin-export (1.2.0) Poetry plugin to export the dependencies to various formats
      1 application plugin

      Dependencies
        - poetry (>=1.2.2,<2.0.0)
        - poetry-core (>=1.3.0,<2.0.0)

If you look at my output, you note that there is a poetry-plugin-export plugin already installed. This is because the poetry export command now uses this plugin. The behavior of the command is not affected for your information. 😉

syncing

To ensure that the environment exactly matches the lock file, the install command has gained a new --sync flag:

$ poetry install --sync

The --sync option can be combined with any of the dependency group-related flags:

$ poetry install --without test--sync
$ poetry install --with docs --sync
$ poetry install --only test

single page repository

Poetry can discover and install packages from single page style of repository that partially follows the structure of a package page in PEP 503. For example, the jax library by Google used this kind of repository. We can add this repository as source with the following command:

$ poetry source add jax https://storage.googleapis.com/jax-releases/jax_releases.html

yanked releases

Poetry now supports yanked releases as defined by PEP 592, for both PyPI and any PEP 503-compatible repository.

Adding a dependency version that is yanked, or installing a project that depends on yanked releases will now raise a warning:

$ poetry add cryptography==37.0.3

...
Warning: The locked version 37.0.3 for cryptography is a yanked version. Reason for being yanked: Regression in OpenSSL.

$ poetry install

...
Warning: The file chosen for install of cryptography 37.0.3 (cryptography-37.0.3-cp36-abi3-manylinux_2_24_x86_64.whl) is yanked. Reason for being yanked: Regression in OpenSSL.

Subdirectory support for Git dependencies

It is now possible to specify a subdirectory from which Poetry should build and install a Git-based dependency.

The syntax used by the add command is the same as pip install/PEP 508 – a #subdirectory= fragment appended to the URL:

$ poetry add git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir

More information about Git dependencies can be found here.

PEP 508 dependency specification parsing

The add command now supports full PEP 508-style dependency specifications, enabling the addition of complex dependency definitions using the ecosystem-standard syntax:

$ poetry add 'pytest-xdist[psutil] (>=2.4.0,<2.5.0); python_version >= "3.7"'

The previous command will result in the following adding in pyproject.toml:

[tool.poetry.dependencies]
pytest-xdist = {version = ">=2.4.0,<2.5.0", markers = "python_version >= \"3.7\"", extras = ["psutil"]}

There are others changes and improvements brought by Poetry but I think these are the most important.

For a detailed list of changes, you can read this blog post.

This is all for this article. Hope you enjoyed it. Take care of yourself and see you next time! 😁

If you like my article and want to continue learning with me, don’t hesitate to follow me here and subscribe to my newsletter on substack 😉