You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tal66 839f7c40ff docs: add `--local` option in `config` 8 hours ago
.github ci: trigger docs on pr sync 5 days ago
assets Update README image 4 years ago
docs docs: add `--local` option in `config` 8 hours ago
src/poetry Adding Pycln QA tool to the pre-commit config (#5234) 12 hours ago
tests Adding Pycln QA tool to the pre-commit config (#5234) 12 hours ago
.cirrus.yml drop py36 from cirrus ci 4 months ago
.flake8 enable strictness flags for mypy (#5531) 1 week ago
.gitignore Add maximum of workers to config (#3516) 6 months ago
.pre-commit-config.yaml Adding Pycln QA tool to the pre-commit config (#5234) 12 hours ago
.pre-commit-hooks.yaml Fix the files pattern 4 months ago
CHANGELOG.md bump to version 1.2.0b1 2 months ago
CODE_OF_CONDUCT.md Add a Code of Conduct (#694) 3 years ago
CONTRIBUTING.md doc: update `pipx` related links to the latest 1 week ago
LICENSE Add LICENSE 4 years ago
README.md remove pipenv comparison 1 week ago
get-poetry.py chore(get-poetry): Fix typo (#5278) 2 months ago
install-poetry.py Wrap long lines to comply with flake8 E501 (#4985) 4 months ago
poetry.lock bump version of poetry-plugin-export to 1.0.2 (rename of implicit dependency group from "default" to "main") 1 week ago
pyproject.toml handle importlib typing at python 3.7 2 days ago
tox.ini Drop python 3.6 support (#5055) 4 months ago

README.md

Poetry: Dependency Management for Python

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

Poetry Install

It supports Python 3.7+.

Tests Status Stable Version Pre-release Version Downloads Discord

The complete documentation is available on the official website.

Installation

Instructions on how to install poetry can be found here. You can also refer here for information on how to enable tab completion in your environment.

Introduction

poetry is a tool to handle dependency installation as well as building and packaging of Python packages. It only needs one file to do all of that: the new, standardized pyproject.toml.

In other words, poetry uses pyproject.toml to replace setup.py, requirements.txt, setup.cfg, MANIFEST.in and the newly added Pipfile.

[tool.poetry]
name = "my-package"
version = "0.1.0"
description = "The description of the package"

license = "MIT"

authors = [
    "Sébastien Eustace <sebastien@eustace.io>"
]

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
toml = "^0.9"
# 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"

[tool.poetry.scripts]
my-script = "my_package:main"

There are some things we can notice here:

  • It will try to enforce semantic versioning as the best practice in version naming.
  • You can specify the readme, included and excluded files: no more MANIFEST.in. poetry will also use VCS ignore files (like .gitignore) to populate the exclude section.
  • Keywords can be specified and will act as tags on the packaging site.
  • The dependencies sections support caret, tilde, wildcard, inequality and multiple requirements.
  • You must specify the python versions for which your package is compatible.

poetry will also detect if you are inside a virtualenv and install the packages accordingly. So, poetry can be installed globally and used everywhere.

poetry also comes with a full fledged dependency resolution library.

Why?

Packaging systems and dependency management in Python are rather convoluted and hard to understand for newcomers. Even for seasoned developers it might be cumbersome at times to create all files needed in a Python project: setup.py, requirements.txt, setup.cfg, MANIFEST.in and the newly added Pipfile.

So I wanted a tool that would limit everything to a single configuration file to do: dependency management, packaging and publishing.

It takes inspiration in tools that exist in other languages, like composer (PHP) or cargo (Rust).

And, finally, I started poetry to bring another exhaustive dependency resolver to the Python community apart from Conda's.

Resources