Managing and Publishing with Poetry¶
Learning Objectives
By the end of this section, you should be able to:
- Explain what Poetry is.
- Explain why Poetry is a great choice for dependency management and packaging in Python.
- Explain what a
pyproject.tomlfile is and how it is useful. - Publish your own package with Poetry
What is Poetry?¶
What is Poetry?
Quote
Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
Basic poetry usage/workflow
Read poetry's basic usage guide
What's that pyproject.toml file?¶
We answer the following questions by referring to the relevant sections in PEP 518. This saves us some time, avoids reproducing existing information, and you end up with some experience reading through PEP's :).
What was the rationale behind PEP518 and the pyproject.toml file? Answer
Why was the TOML format chosen? Answer
Why where YAML, JSON, and the configparser rejected? Answer
To see the pyproject.toml file in action, take a look at the following example.
Example: quizli's pyproject.toml file¶
Example
# (1) Annotating our package
# First we define some basic descriptions about our project.
# More information about valid sections can be found in this link:
# https://python-poetry.org/docs/master/pyproject/
[tool.poetry]
name = "quizli"
homepage = "https://github.com/pwenker/quizli"
documentation = "https://pwenker.github.io/quizli"
version = "1.0.0"
description = "An educational project teaching how to open-source an interactive Python quiz app"
authors = ["Pascal Wenker <pwenker@posteo.de>"]
readme = "README.md"
license = "MIT"
classifiers = [ # https://pypi.org/classifiers/
"Programming Language :: Python :: 3 :: Only",
"Environment :: Console",
"Intended Audience :: Education",
"Intended Audience :: Developers",
"Natural Language :: English",
"Topic :: Documentation",
"Topic :: Education",
"Topic :: Software Development",
"Typing :: Typed",
]
# (2) Defining an entrypoint for our CLI
# Here we define the entrypoint to our app. Since we want to let
# users run the app with the `quizli` command, we define it as such
# below
[tool.poetry.scripts]
quizli = "quizli.main:app"
# (3) Declaring Dependencies
# The following section defines the dependencies of our project.
# Note that poetry lets us split them up in
# - regular dependencies, and
# - dev-dependencies.
# In this way, a users can install it with `poetry install --no-dev`
# to not install the development dependencies they don't need.
[tool.poetry.dependencies]
python = "^3.8"
rich = "^11.0.0"
typer-cli = "^0.0.12"
[tool.poetry.dev-dependencies]
# Testing
pytest = "^7.0.1"
pytest-cov = "^3.0.0"
typing-extensions = "^4.1.1"
# Documentation
mkdocs-material = "^8.1.8"
## Plugins
mkdocstrings = "^0.17.0"
mkdocs-jupyter = "^0.19.0"
mkdocs-git-revision-date-localized-plugin = "^1.0.0"
# (4) Setting the build-sytem
# Here, we declare that we want poetry to build our package.
[build-system] # See: https://www.python.org/dev/peps/pep-0518/#id27
requires = ["poetry-core>=1.0.0"] # For more information see: PEP 518
build-backend = "poetry.core.masonry.api" # For more information see: PEP 517
Poetry's new dependency groups
With version 1.2.0 poetry allows you to organize your dependencies by groups.
For more information about this dependency groups feature, see the Managing dependencies section in the docs.
Publishing the package¶
Info
In order to publish the package to PyPi you need to create an account at https://pypi.org/.
To build & publish the package, we can again use Poetry:
- Build the package:
poetry build - Publish it:
poetry publish
That's all, the package is now available at https://pypi.org/project/quizli/ and
can be installed with pip install quizli.
Resources