tox uses pluggy to customize the default behaviour. For example the
following code snippet would define a new
--magic command line interface flag the user can specify:
from tox.config.cli.parser import ToxParser from tox.plugin import impl @impl def tox_add_option(parser: ToxParser) -> None: parser.add_argument("--magic", action="store_true", help="magical flag")
You can define such hooks either in a package installed alongside tox or within a
toxfile.py found alongside your
tox configuration file (root of your project).
- tox.plugin.NAME = 'tox'#
the name of the tox hook
decorator to mark tox plugin hooks
Register new tox environment type. You can register:
run environment: by default this is a local subprocess backed virtualenv Python
packaging environment: by default this is a PEP-517 compliant local subprocess backed virtualenv Python
ToxEnvRegister) – a object that can be used to register new tox environment types
- Return type:
Add a command line argument. This is the first hook to be called, right after the logging setup and config source discovery.
- tox.plugin.spec.tox_add_core_config(core_conf, state)#
Called when the core configuration is built for a tox environment.
- tox.plugin.spec.tox_add_env_config(env_conf, state)#
Called when configuration is built for a tox environment.
EnvConfigSet) – the core configuration object
State) – the global tox state object
- Return type:
Called before the commands set is executed.
- tox.plugin.spec.tox_after_run_commands(tox_env, exit_code, outcomes)#
Called after the commands set is executed.
Adoption of a plugin under tox-dev Github organization#
You’re free to host your plugin on your favorite platform, however the core tox development is happening on Github,
tox-dev org organization. We are happy to adopt tox plugins under the
tox-dev organization if:
we determine it’s trying to solve a valid use case and it’s not malicious (e.g. no plugin that deletes the users home directory),
it’s released on PyPI with at least 100 downloads per month (to ensure it’s a plugin used by people).
What’s in for you in this:
you get owner rights on the repository under the tox-dev organization,
exposure of your plugin under the core umbrella,
backup maintainers from other tox plugin development.
How to apply:
create an issue under the
tox-dev/toxGithub repository with the title Adopt plugin <name>,
wait for the green light by one of our maintainers (see Current maintainers),
follow the guidance by Github,
(optionally) add at least one other people as co-maintainer on PyPI.
Migration from tox 3#
This section explains how the plugin interface changed between tox 3 and 4, and provides guidance for plugin developers on how to migrate.
With tox 4 the Python discovery is performed
tox.tox_env.python.virtual_env.api._get_python that delegates the job
virtualenv. Therefore first define a new virtualenv discovery mechanism and then set that by setting the
VIRTUALENV_DISCOVERY environment variable.
Register new packager types via