Specifying your dependencies with Poetry¶
Declaring your project metadata¶
Poetry is a PEP 517-compliant build backend, which means that
it can generate your project
metadata
using a standardized interface that can be consumed directly by pip.
To do that, first make sure that
the build-system
section of your pyproject.toml
declares the build backend as follows:
[build-system]
requires = ["poetry_core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
Then, you will be able to install it on Read the Docs just using pip, with a configuration like this:
version: 2
build:
os: ubuntu-20.04
tools:
python: "3.9"
python:
install:
- method: pip
path: .
For example, the rich Python library uses Poetry to declare its library dependencies and installs itself on Read the Docs with pip.
Locking your dependencies¶
With your pyproject.toml
file you are free to specify the dependency
versions
that are most appropriate for your project,
either by leaving them unpinned or setting some constraints.
However, to achieve Reproducible Builds
it is better that you lock your dependencies,
so that the decision to upgrade any of them is yours.
Poetry does this using poetry.lock
files
that contain the exact versions of all your transitive dependencies
(that is, all the dependencies of your dependencies).
The first time you run poetry install
in your project directory
Poetry will generate a new poetry.lock
file
with the versions available at that moment.
You can then commit your poetry.lock to version
control
so that Read the Docs also uses these exact dependencies.