tox plugins¶
New in version 2.0.
With tox-2.0 a few aspects of tox running can be experimentally modified by writing hook functions. The list of of available hook function is to grow over time on a per-need basis.
writing a setuptools entrypoints plugin¶
If you have a tox_MYPLUGIN.py
module you could use the following
rough setup.py
to make it into a package which you can upload to the
Python packaging index:
# content of setup.py
from setuptools import setup
if __name__ == "__main__":
setup(
name='tox-MYPLUGIN',
description='tox plugin decsription',
license="MIT license",
version='0.1',
py_modules=['tox_MYPLUGIN'],
entry_points={'tox': ['MYPLUGIN = tox_MYPLUGIN']},
install_requires=['tox>=2.0'],
)
If installed, the entry_points
part will make tox see and integrate
your plugin during startup.
You can install the plugin for development (“in-place”) via:
pip install -e .
and later publish it via something like:
python setup.py sdist register upload
Writing hook implementations¶
A plugin module defines one or more hook implementation functions
by decorating them with tox’s hookimpl
marker:
from tox import hookimpl
@hookimpl
def tox_addoption(parser):
# add your own command line options
@hookimpl
def tox_configure(config):
# post process tox configuration after cmdline/ini file have
# been parsed
If you put this into a module and make it pypi-installable with the tox
entry point you’ll get your code executed as part of a tox run.
tox hook specifications and related API¶
Hook specifications for tox.
-
tox.hookspecs.
tox_addoption
(parser)[source]¶ add command line options to the argparse-style parser object.
-
tox.hookspecs.
tox_configure
(config)[source]¶ called after command line options have been parsed and the ini-file has been read. Please be aware that the config object layout may change as its API was not designed yet wrt to providing stability (it was an internal thing purely before tox-2.0).
-
tox.hookspecs.
tox_get_python_executable
(envconfig)[source]¶ return a python executable for the given python base name. The first plugin/hook which returns an executable path will determine it.
envconfig
is the testenv configuration which contains per-testenv configuration, notably the.envname
and.basepython
setting.
-
tox.hookspecs.
tox_runtest
(venv, redirect)[source]¶ [experimental] run the tests for this venv.
Note
This hook uses
firstresult=True
(see pluggy) – hooks implementing this will be run until one returns non-None
.
-
tox.hookspecs.
tox_runtest_post
(venv)[source]¶ [experimental] perform arbitrary action after running tests for this venv.
This could be used to have per-venv test reporting of pass/fail status.
-
tox.hookspecs.
tox_runtest_pre
(venv)[source]¶ [experimental] perform arbitrary action before running tests for this venv.
This could be used to indicate that tests for a given venv have started, for instance.
-
tox.hookspecs.
tox_testenv_create
(venv, action)[source]¶ [experimental] perform creation action for this venv.
Some example usage:
- To add behavior but still use tox’s implementation to set up a
virtualenv, implement this hook but do not return a value (or explicitly
return
None
). - To override tox’s virtualenv creation, implement this hook and return
a non-
None
value.
Note
This api is experimental due to the unstable api of
tox.venv.VirtualEnv
.Note
This hook uses
firstresult=True
(see pluggy) – hooks implementing this will be run until one returns non-None
.- To add behavior but still use tox’s implementation to set up a
virtualenv, implement this hook but do not return a value (or explicitly
return
-
tox.hookspecs.
tox_testenv_install_deps
(venv, action)[source]¶ [experimental] perform install dependencies action for this venv.
Some example usage:
- To add behavior but still use tox’s implementation to install
dependencies, implement this hook but do not return a value (or
explicitly return
None
). One use-case may be to install (or ensure) non-python dependencies such as debian packages. - To override tox’s installation of dependencies, implement this hook
and return a non-
None
value. One use-case may be to install via a different installation tool such as pip-accel or pip-faster.
Note
This api is experimental due to the unstable api of
tox.venv.VirtualEnv
.Note
This hook uses
firstresult=True
(see pluggy) – hooks implementing this will be run until one returns non-None
.- To add behavior but still use tox’s implementation to install
dependencies, implement this hook but do not return a value (or
explicitly return
-
class
tox.config.
Parser
[source]¶ command line and ini-parser control object.
-
add_argument
(*args, **kwargs)[source]¶ add argument to command line parser. This takes the same arguments that
argparse.ArgumentParser.add_argument
.
-
add_testenv_attribute
(name, type, help, default=None, postprocess=None)[source]¶ add an ini-file variable for “testenv” section.
Types are specified as strings like “bool”, “line-list”, “string”, “argv”, “path”, “argvlist”.
The
postprocess
function will be called for each testenv likepostprocess(testenv_config=testenv_config, value=value)
wherevalue
is the value as read from the ini (or the default value) andtestenv_config
is atox.config.TestenvConfig
instance which will receive all ini-variables as object attributes.Any postprocess function must return a value which will then be set as the final value in the testenv section.
-
-
class
tox.config.
Config
[source]¶ Global Tox config object.
-
envconfigs
= None¶ dictionary containing envname to envconfig mappings
-
option
= None¶ option namespace containing all parsed command line options
-
-
class
tox.config.
TestenvConfig
[source]¶ Testenv Configuration object. In addition to some core attributes/properties this config object holds all per-testenv ini attributes as attributes, see “tox –help-ini” for an overview.
-
config
= None¶ global tox config object
-
envname
= None¶ test environment name
-
envpython
¶ path to python executable.
-
factors
= None¶ set of factors
-
get_envsitepackagesdir
()[source]¶ return sitepackagesdir of the virtualenv environment. (only available during execution, not parsing)
-
missing_subs
= None¶ Holds substitutions that could not be resolved.
Pre 2.8.1 missing substitutions crashed with a ConfigError although this would not be a problem if the env is not part of the current testrun. So we need to remember this and check later when the testenv is actually run and crash only then.
-
python_info
¶ return sitepackagesdir of the virtualenv environment.
-
-
class
tox.venv.
VirtualEnv
[source]¶ -
getcommandpath
(name, venv=True, cwd=None)[source]¶ Return absolute path (str or localpath) for specified command name.
- If it’s a local path we will rewrite it as as a relative path.
- If venv is True we will check if the command is coming from the venv or is whitelisted to come from external.
-
name
¶ test environment name.
-
path
¶ Path to environment base dir.
-