Introduction on Poetry - Python dependency management and packaging made easy

Basic usage

Mon, 01 Jan 0001 00:00:00 +0000

Basic usage

For the basic usage introduction we will be installing pendulum, a datetime library. If you have not yet installed Poetry, refer to the Introduction chapter.

Project setup

First, let’s create our new project, let’s call it poetry-demo:

poetry new poetry-demo

This will create the poetry-demo directory with the following content:

poetry-demo
├── pyproject.toml
├── README.md
├── src
│ └── poetry_demo
│ └── __init__.py
└── tests
 └── __init__.py

The pyproject.toml file is what is the most important here. This will orchestrate your project and its dependencies. For now, it looks like this:

Building extension modules

Mon, 01 Jan 0001 00:00:00 +0000

Building Extension Modules

Warning

While this feature has been around since almost the beginning of the Poetry project and has needed minimal changes, it is still considered unstable. You can participate in the discussions about stabilizing this feature here.

And as always, your contributions towards the goal of improving this feature are also welcome.

Poetry allows a project developer to introduce support for, build and distribute native extensions within their project. In order to achieve this, at the highest level, the following steps are required.

Commands

Mon, 01 Jan 0001 00:00:00 +0000

Commands

You’ve already learned how to use the command-line interface to do some things. This chapter documents all the available commands.

To get help from the command-line, simply call poetry to see the complete list of commands, then --help combined with any of those can give you more information.

Global Options

--verbose (-v|vv|vvv): Increase the verbosity of messages: “-v” for normal output, “-vv” for more verbose output and “-vvv” for debug.

Note

You can also set the verbosity level using the SHELL_VERBOSITY environment variable. This is useful in CI/CD pipelines or scripts where you cannot easily modify command-line arguments.

Community

Mon, 01 Jan 0001 00:00:00 +0000

Community

Badge

For any projects using Poetry, you may add its official badge somewhere prominent like the README.

Markdown

[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)

reStructuredText

.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
 :alt: Poetry
 :target: https://python-poetry.org/

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration

Poetry can be configured via the config command (see more about its usage here) or directly in the config.toml file that will be automatically created when you first run that command. This file can typically be found in one of the following directories:

macOS: ~/Library/Application Support/pypoetry
Windows: %APPDATA%\pypoetry

For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. That means, by default ~/.config/pypoetry.

Local configuration

Poetry also provides the ability to have settings that are specific to a project by passing the --local option to the config command.

Contributing to Poetry

Mon, 01 Jan 0001 00:00:00 +0000

Contributing to Poetry

First off, thanks for taking the time to contribute!

The following is a set of guidelines for contributing to Poetry on GitHub. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request.

How to contribute

Reporting bugs

This section guides you through submitting a bug report for Poetry. Following these guidelines helps maintainers and the community understands your report, reproduces the behavior, and finds related reports.

Dependency specification

Mon, 01 Jan 0001 00:00:00 +0000

Dependency specification

Dependencies for a project can be specified in various forms, which depend on the type of the dependency and on the optional constraints that might be needed for it to be installed.

`project.dependencies` and `tool.poetry.dependencies`

Prior Poetry 2.0, dependencies had to be declared in the tool.poetry.dependencies section of the pyproject.toml file.

[tool.poetry.dependencies]
requests = "^2.13.0"

With Poetry 2.0, you should consider using the project.dependencies section instead.

[project]
# ...
dependencies = [
 "requests (>=2.23.0,<3.0.0)"
]

While dependencies in tool.poetry.dependencies are specified using toml tables, dependencies in project.dependencies are specified as strings according to PEP 508.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

FAQ

Why is the dependency resolution process slow?

While the dependency resolver at the heart of Poetry is highly optimized and should be fast enough for most cases, with certain sets of dependencies, it can take time to find a valid solution.

This is due to the fact that not all libraries on PyPI have properly declared their metadata and, as such, they are not available via the PyPI JSON API. At this point, Poetry has no choice but to download the packages and inspect them to get the necessary information. This is an expensive operation, both in bandwidth and time, which is why it seems this is a long process.

Libraries

Mon, 01 Jan 0001 00:00:00 +0000

Libraries

This chapter will tell you how to make your library installable through Poetry.

Versioning

Poetry requires PEP 440-compliant versions for all projects.

While Poetry does not enforce any release convention, it used to encourage the use of semantic versioning within the scope of PEP 440 and supports version constraints that are especially suitable for semver.

Note

As an example, 1.0.0-hotfix.1 is not compatible with PEP 440. You can instead choose to use 1.0.0-post1 or 1.0.0.post1.

Lock file

For your library, you may commit the poetry.lock file if you want to. This can help your team to always test against the same dependency versions. However, this lock file will not have any effect on other projects that depend on it. It only has an effect on the main project.

Managing dependencies

Mon, 01 Jan 0001 00:00:00 +0000

Managing dependencies

Poetry supports specifying main dependencies in the project.dependencies section of your pyproject.toml according to PEP 621. For legacy reasons and to define additional information that are only used by Poetry the tool.poetry.dependencies sections can be used.

See Dependency specification for more information.

Dependency groups

Poetry provides a way to organize your dependencies by groups.

The dependencies declared in project.dependencies respectively tool.poetry.dependencies are part of an implicit main group. Those dependencies are required by your project during runtime.

Managing environments

Mon, 01 Jan 0001 00:00:00 +0000

Managing environments

Poetry makes project environment isolation one of its core features.

What this means is that it will always work isolated from your global Python installation. To achieve this, it will first check if it’s currently running inside a virtual environment. If it is, it will use it directly without creating a new one. But if it’s not, it will use one that it has already created or create a brand new one for you.

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Plugins

Poetry supports using and building plugins if you wish to alter or expand Poetry’s functionality with your own.

For example if your environment poses special requirements on the behaviour of Poetry which do not apply to the majority of its users or if you wish to accomplish something with Poetry in a way that is not desired by most users.

In these cases you could consider creating a plugin to handle your specific logic.

pre-commit hooks

Mon, 01 Jan 0001 00:00:00 +0000

pre-commit hooks

pre-commit is a framework for building and running git hooks. See the official documentation for more information: pre-commit.com

This document provides a list of available pre-commit hooks provided by Poetry.

Note

If you specify the args: for a hook in your .pre-commit-config.yaml, the defaults are overwritten. You must fully specify all arguments for your hook if you make use of args:.

Note

If the pyproject.toml file is not in the root directory, you can specify args: ["-C", "./subdirectory"].

poetry-check

The poetry-check hook calls the poetry check command to make sure the poetry configuration does not get committed in a broken state.

Repositories

Mon, 01 Jan 0001 00:00:00 +0000

Repositories

Poetry supports the use of PyPI and private repositories for discovery of packages as well as for publishing your projects.

By default, Poetry is configured to use the PyPI repository, for package installation and publishing.

So, when you add dependencies to your project, Poetry will assume they are available on PyPI.

This represents most cases and will likely be enough for most users.

Private Repository Example

Installing from private package sources

By default, Poetry discovers and installs packages from PyPI. But, you want to install a dependency to your project for a simple API repository? Let’s do it.

The pyproject.toml file

Mon, 01 Jan 0001 00:00:00 +0000

The `pyproject.toml` file

In package mode, the only required fields are name and version (either in the project section or in the tool.poetry section). Other fields are optional. In non-package mode, the name and version fields are required if using the project section.

Note

Run poetry check to print warnings about deprecated fields.

The `project` section

The project section of the pyproject.toml file according to the specification of the PyPA.

name

The name of the package. Always required when the project section is specified

Introduction on Poetry - Python dependency management and packaging made easy

Basic usage

Basic usage

Project setup

Building extension modules

Building Extension Modules

Commands

Commands

Global Options

Community

Community

Badge

Configuration

Configuration

Local configuration

Contributing to Poetry

Contributing to Poetry

How to contribute

Reporting bugs

Dependency specification

Dependency specification

project.dependencies and tool.poetry.dependencies

FAQ

FAQ

Why is the dependency resolution process slow?

Libraries

Libraries

Versioning

Lock file

Managing dependencies

Managing dependencies

Dependency groups

Managing environments

Managing environments

Plugins

Plugins

pre-commit hooks

pre-commit hooks

poetry-check

Repositories

Repositories

Private Repository Example

Installing from private package sources

The pyproject.toml file

The pyproject.toml file

The project section

name

`project.dependencies` and `tool.poetry.dependencies`

The `pyproject.toml` file

The `project` section