enpaul/tox-poetry-installer
1
0
Fork 0
mirror of https://github.com/enpaul/tox-poetry-installer.git synced 2025-11-03 07:39:20 +00:00
Code Issues Projects Releases Wiki Activity

Add more detailed project overview

Browse Source
This commit is contained in:
Ethan Paul
2020-09-23 02:50:51 -04:00
parent c5bdb69063
commit 3711f4b42f
1 changed files with 57 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@@ -3,4 +3,60 @@
A [Tox](https://tox.readthedocs.io/en/latest/) plugin for installing Tox environment
dependencies using [Poetry](https://python-poetry.org/) from the Poetry lockfile.
Very early prototype, still under development
⚠️ **This project is a very, very early prototype and should not be used in any production
capacity.**
## Why would I use this?
[The point of using a lockfile is to create reproducable builds](https://docs.gradle.org/current/userguide/dependency_locking.html). One of the main points of Tox is to [allow a Python
package to be built and tested in multiple environments](https://tox.readthedocs.io/en/latest/#what-is-tox). However, in the Tox configuration file the dependencies are specified with
standard dynamic ranges and passed directly to Pip. This means that the reproducability
a lockfile brings to a project is circumvented when running the tests.
The obvious solution to this problem is to add the dependencies required for testing to the
lockfile as development dependencies so that they are locked along with the primary dependencies
of the project. The only remaining question however, is how to install the dev-dependencies from
the lockfile into the Tox environment when Tox sets it up. [For very good reason](https://dev.to/elabftw/stop-using-sudo-pip-install-52mn) Tox uses independent
[virtual environments](https://docs.python.org/3/tutorial/venv.html) for each environment a
project defines, so there needs to be a way to install a locked dependency into a Tox
environment.
This is where this plugin comes in.
Traditionally Tox environments specify dependencies and their corresponding versions inline in
[PEP-440](https://www.python.org/dev/peps/pep-0440/) format like below:
```ini
[testenv]
description = Run the tests
deps =
foo == 1.2.3
bar >=1.3,<2.0
baz
```
This runs into the problem outlined above: many different versions of the `bar` dependency
could be installed depending on what the latest version is that matches the defined range. The
`baz` dependency is entirely unpinned making it a true wildcard, and even the seemingly static
`foo` dependency could result in subtly different files being downloaded depending on what's
available in the upstream mirrors.
However these same versions, specified in the [pyproject.toml](https://snarky.ca/what-the-heck-is-pyproject-toml/) file, result in reproducible
installations when using `poetry install` because they each have a specific version and file
hash specified in the lockfile. The versions specified in the lockfile are updated only when
`poetry update` is run.
This plugin allows environment dependencies to be specified in the [tox.ini](https://tox.readthedocs.io/en/latest/config.html) configuration file
just by name. The package is automatically retrieved from the lockfile and the Poetry backend
is used to install the singular locked package version to the Tox environment. When the
lockfile is updated, the Tox environment will automatically install the newly locked package
as well. All dependency requirements are specified in one place (pyproject.toml), all
dependencies have a locked version, and everything is installed from that source of truth.
## Planned features
* Per-environment disabling (i.e. fallback to the default Tox installation backend)
* Detection of lockfile changes that trigger Tox environment recreation
* Tests