Python packaging and dependency management using poetry

Introduction

Dependency management is a technique for declaring, resolving and using dependencies required by the project in an automated fashion. There are several different approaches to dealing with dependencies in Python. In this article, I’ll show you how manage your project’s dependencies using Poetry. Poetry is a tool for dependency management and packaging in Python. It allows you to declare dependencies of your project and it will manage them for you.

Prerequisite

Poetry requires Python 2.7 or 3.4+. It is multi-platform and the goal is to make it work equally well on different operating systems.

Installation

Poetry provides a custom installer that will install poetry isolated from the rest of your system by vendorizing its dependencies. This is the recommended way of installing poetry. Alternatively you can install it on top of your existing python using pip install command.

On Linux/macOS

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

On windows (PowerShell)

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python

The installer installs the poetry tool to Poetry's bin directory. On Unix it is located at $HOME/.poetry/bin and on Windows at %USERPROFILE%\.poetry\bin And on either operating systems you should see these outputs:

Retrieving Poetry metadata
# Welcome to Poetry!
This will download and install the latest version of Poetry,
a dependency and package manager for Python.
It will add the `poetry` command to Poetry’s bin directory, located at:
$HOME/.poetry/bin
This path will then be added to your `PATH` environment variable by
modifying the profile file located at:
$HOME/.profile
You can uninstall at any time by executing this script with the — uninstall option,
and these changes will be reverted.
Installing version: 1.0.5
 — Downloading poetry-1.0.5-linux.tar.gz (23.00MB)
Poetry (1.0.5) is installed now. Great!
To get started you need Poetry's bin directory ($HOME/.poetry/bin) in your `PATH`
environment variable. Next time you log in this will be done
automatically.
To configure your current shell run `source $HOME/.poetry/env`

Use poetry --version to see if the installation succeeds. You should see something like Poetry 1.0.5 as the results.

Usage

Poetry helps you declare, manage and install dependencies of Python projects, ensuring you have the right stack everywhere.

Install dependencies and create virtual environment

Poetry uses only one file (pyproject.toml) to manage your projects dependencies. In other words, poetry uses pyproject.toml to replace setup.py, requirements.txt, setup.cfg, MANIFEST.in and Pipfile.

[tool.poetry]
name = "test-package"
version = "0.1.0"
description = "The description of the package goes here"
license = "MIT"
authors = [
"MehrdadEP <mehrdadep@outlook.com>"
]
readme = 'README.md'  # Markdown files are supported
repository = "https://github.com/python-poetry/poetry"
homepage = "https://github.com/python-poetry/poetry"
keywords = ['packaging', 'poetry']

[tool.poetry.dependencies]
python = "~2.7 || ^3.2"  # Compatible python versions must be declared here
# Dependencies with extras
requests = { version = "^2.13", extras = [ "security" ] }
# Python specific dependencies with prereleases allowed
pathlib2 = { version = "^2.2", python = "~2.7", allow-prereleases = true }
# Git dependencies
cleo = { git = "https://github.com/sdispater/cleo.git", branch = "master" }

# Optional dependencies (extras)
pendulum = { version = "^1.4", optional = true }

[tool.poetry.dev-dependencies]
pytest = "^3.0"
pytest-cov = "^2.4"

Use install command to create a virtual environment and install all dependencies for the first time

poetry install

Other useful commands

1. Add a new dependency to your existing environment using add command

poetry add pendulum

2. Build a package from your project using build command

poetry build

3. Publish your project to PyPI using publish command

poetry publish

4. Keep track of your project’s dependencies and have an insight on them using show command

poetry show --tree
poetry show --latest

5. Create a Python Project with Poetry using new command (This command creates an empty project and required files)

poetry new test-project

6. To activate an existing virtual environment use shell command inside of the project’s root directory

poetry shell

Uninstalling poetry

If you decide Poetry isn’t your thing, you can completely remove it from your system by running the installer again with the --uninstall option or by setting the POETRY_UNINSTALL environment variable before executing the installer.

python get-poetry.py --uninstall
POETRY_UNINSTALL=1 python get-poetry.py