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)

add command line options to the argparse-style parser object.

tox.hookspecs.tox_configure(config)

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)

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_testenv_create(venv, action)

[experimental] perform creation action for this venv.

tox.hookspecs.tox_testenv_install_deps(venv, action)

[experimental] perform install dependencies action for this venv.

class tox.config.Parser

command line and ini-parser control object.

add_argument(*args, **kwargs)

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)

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 like postprocess(testenv_config=testenv_config, value=value) where value is the value as read from the ini (or the default value) and testenv_config is a tox.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.

add_testenv_attribute_obj(obj)

add an ini-file variable as an object.

This works as the add_testenv_attribute function but expects “name”, “type”, “help”, and “postprocess” attributes on the object.

class tox.config.Config

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

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_envbindir()

path to directory where scripts/binaries reside.

get_envpython()

path to python/jython executable.

get_envsitepackagesdir()

return sitepackagesdir of the virtualenv environment. (only available during execution, not parsing)

python_info

return sitepackagesdir of the virtualenv environment.

class tox.venv.VirtualEnv

getcommandpath(name, venv=True, cwd=None)

return absolute path (str or localpath) for specified command name. If it’s a localpath 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.

update(action)

return status string for updating actual venv to match configuration. if status string is empty, all is ok.

class tox.session.Session

(unstable API). the session object that ties together configuration, reporting, venv creation, testing.

get_installpkg_path()

Returns:Path to the distribution Return type:py.path.local

getvenv(name)

return a VirtualEnv controler object for the ‘name’ env.

installpkg(venv, path)

Install package in the specified virtual environment.

:param tox.config.VenvConfig: Destination environment :param str path: Path to the distribution package. :return: True if package installed otherwise False. :rtype: bool