Plugins — tox 2.9.0rc2.dev63 documentation

# Plugins

New in version 2.0.

Sonce tox 2 a few aspects of tox running can be experimentally modified by writing hook functions. The list of of available hook function is growing on a per-need basis.

## Simple example

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

## Write 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.

## Hook specifications and 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_runtest`(venv, redirect)

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

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

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

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

`tox.hookspecs.` `tox_testenv_install_deps`(venv, action)

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

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)

  `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`
  `getcommandpath`(name, venv=True, cwd=None)

    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.

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

    Parameters: | venv (VenvConfig) – Destination environment path (str) – Path to the distribution package.
    Returns: | True if package installed otherwise False.
    Return type: | bool