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

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

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