tox-poetry-installer/README.md

tox-poetry-installer

A plugin for Tox that allows test environment dependencies to be installed using Poetry using its lockfile.

⚠️ This project is alpha software and should not be used in a production capacity ⚠️

Documentation

• Installation and Usage
• Limitations
• What problem does this solve? (Why would I use this?)
• Developing
• Contributing
• Roadmap
  • Path to Beta
  • Path to Stable

Related resources:

• Poetry Python Project Manager
• Tox Automation Project
• Tox plugins

Installation and Usage

1. Install the plugin from PyPI:

poetry add tox-poetry-installer --dev

2. Remove all version specifications from the environment dependencies in tox.ini:

# This...
[testenv]
description = My cool test environment
deps =
    requests >=2.19,<3.0
    toml == 0.10.0
    pytest >=5.4

# ...becomes this:
[testenv]
description = My cool test environment
deps =
    requests
    toml
    pytest

3. Run Tox with the --recreate flag to rebuild the test environments:

poetry run tox --recreate

4. 💸 Profit 💸

Limitations

• In general, any command line or INI settings that affect how Tox installs environment dependencies will be disabled by installing this plugin. A non-exhaustive and untested list of the INI options that are not expected to work with this plugin is below:

  • install_command
  • pip_pre
  • downloadcache (deprecated)
  • download
  • indexserver
  • usedevelop
  • extras

• When the plugin is enabled all dependencies for all environments will use the Poetry backend provided by the plugin; this functionality cannot be disabled on a per-environment basis.

• Alternative versions cannot be specified alongside versions from the lockfile. All dependencies are installed from the lockfile and alternative versions cannot be specified in the Tox configuration.

What problems does this solve?

The point of using a lockfile is to create reproducable builds. One of the main points of Tox is to allow a Python package to be built and tested in multiple environments. 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 Tox uses independent virtual environments 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 format like below:

[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 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 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.

Developing

This project requires Poetry-1.0+, see the installation instructions here.

# Clone the repository...
# ...over HTTPS
git clone https://github.com/enpaul/tox-poetry-installer.git
# ...over SSH
git clone git@github.com:enpaul/tox-poetry-installer.git

# Create a the local project virtual environment and install dependencies
cd tox-poetry-installer
poetry install

# Install pre-commit hooks
poetry run pre-commit install

# Run tests and static analysis
poetry run tox

Contributing

All project contributors and participants are expected to adhere to the Contributor Covenant Code of Conduct, Version 2.

• To report a bug, request a feature, or ask for assistance, please open an issue on the Github repository.
• To report a security concern or code of conduct violation, please contact the project author directly at ethan dot paul at enp dot one.
• To submit an update, please fork the repository and open a pull request.

Roadmap

This project is under active development and is classified as alpha software, not yet ready usage in production systems.

• Beta classification will be assigned when the initial feature set is finalized
• Stable classification will be assigned when the test suite covers an acceptable number of use cases

Path to Beta

• Verify that primary package dependencies (from the .package env) are installed correctly using the Poetry backend.
• Support the extras Tox configuration option
• Add per-environment Tox configuration option to fall back to default installation backend.
• Add detection of a changed lockfile to automatically trigger a rebuild of Tox environments when necessary.
• Add warnings when an unsupported Tox configuration option is detected while using the Poetry backend.
• Add trivial tests to ensure the project metadata is consistent between the pyproject.toml and the module constants.
• Update to use poetry-core Tox configuration option) and improve robustness of the Tox and Poetry module imports to avoid potentially breaking API changes in upstream packages.

Path to Stable

Everything in Beta plus...

• Add tests for each feature version of Tox between 2.3 and 3.20
• Add tests for Python-3.6, 3.7, and 3.8
• Add Github Actions based CI
• Add CI for CPython, PyPy, and Conda
• Add CI for Linux and Windows