tox / doc / config.txt

Full commit
.. be in -*- rst -*- mode!

tox configuration specification

.. _ConfigParser:

``tox.ini`` files uses the standard ConfigParser_ "ini-style" format.
Below you find the specification, but you might want to skim some
:doc:`examples` first and use this page as a reference.

Tox global settings

List of optional global options::

    minversion=ver    # minimally required tox version
    toxworkdir=path   # tox working directory, defaults to {toxinidir}/.tox
    setupdir=path     # defaults to {toxinidir}
    distdir=path      # defaults to {toxworkdir}/dist
    distshare=path    # defaults to {homedir}/.tox/distshare
    envlist=ENVLIST   # defaults to the list of all environments

``tox`` autodetects if it is running in a Jenkins_ context
(by checking for existence of the ``JENKINS_URL`` environment variable)
and will first lookup global tox settings in this section::

    ...               # override [tox] settings for the hudson context
    # note: for hudson distshare defaults to ``{toxworkdir}/distshare``.

envlist setting

Determining the environment list that ``tox`` is to operate one
happens in this order:

* command line option ``-eENVLIST``
* environment variable ``TOXENV``
* ``tox.ini`` file's ``envlist``

Virtualenv test environment settings

Test environments are defined by a::


section.  The ``NAME`` will be the name of the virtual environment.
Defaults for each setting in this section are looked up in the::


testenvironment default section.

Complete list of settings that you can put into ``testenv*`` sections:

.. confval:: basepython=NAME-OR-PATH

    name or path to a Python interpreter which will be used for creating
    the virtual environment. **default**: interpreter used for tox invocation.

.. confval:: commands=ARGVLIST

    the commands to be called for testing. Each command is defined
    by one or more lines; a command can have multiple lines if a line
    ends with the ``\`` character in which case the subsequent line
    will be appended (and may contain another ``\`` character ...).
    For eventually performing a call to ``subprocess.Popen(args, ...)``
    ``args`` are determined by splitting the whole command by whitespace.

.. confval:: changedir=path

    change to this working directory when executing the test command.
    **default**: ``{toxinidir}``

.. confval:: deps=MULTI-LINE-LIST

    test-specific dependencies be installed into the environment prior to project
    package installation.  Each line defines a dependency, which will be
    passed to easy_install/pip for processing.  A line specify a file,
    an URL or a package name.  You can additionally specify
    an :confval:`indexserver` to use for installing this dependency.
    All derived dependencies (deps required by the dep) will then be
    retrieved from the specified indexserver::

        deps = :myindexserver:pkg

.. confval:: setenv=MULTI-LINE-LIST
   .. versionadded:: 0.9

   each line contains a NAME=VALUE environment variable setting which
   will be used for all test command invocations as well as for installing
   the sdist package into a virtual environment.

.. confval:: recreate=True|False(default)

    Always recreate virtual environment if this option is True.

.. confval:: downloadcache=path

    (pip only) use this directory for caching downloads - this defaults to the
    environment variable ``PIP_DOWNLOAD_CACHE`` if it is set.
    **default**: no download cache will be used.
    **note**: if creating multiple environments use of a download cache greatly
    speeds up the testing process.

.. confval:: distribute=True|False

    Set to ``False`` if you want to use setuptools_ instead of the default
    distribute_ in the virtual environment.
    **default:** True.

.. confval:: sitepackages=True|False

    Set to ``True`` if you want to create virtual environments that also
    have access to globally installed packages.  **default:** False, meaning
    that virtualenvs will be created with ``--no-site-packages`` by default.

.. confval:: args_are_paths=BOOL

    treat positional arguments passed to ``tox`` as file system paths
    and - if they exist on the filesystem - rewrite them according
    to the ``changedir``.
    **default**: True (due to the exists-on-filesystem check it's usually
    safe to try rewriting).

.. confval:: envtmpdir=path

    defines a temporary directory for the virtualenv which will be cleared
    each time before the group of test commands is invoked.
    **default**: ``{envdir}/tmp``

.. confval:: envlogdir=path

    defines a directory for logging where tox will put logs of tool
    **default**: ``{envdir}/log``

.. confval:: indexserver

   .. versionadded:: 0.9

   Multi-line ``name = URL`` definitions of python package servers.
   Depedencies can specify using a specified index server through the
   ``:indexservername:depname`` pattern.  The ``default`` indexserver
   definition determines where unscoped dependencies and the sdist install
   installs from.  Example::

        indexserver =
            default =

   will make tox install all dependencies from this PYPI index server
   (including when installing the project sdist package).


Any ``key=value`` setting in an ini-file can make use
of value substitution through the ``{...}`` string-substitution pattern.

Globally available substitutions

    the directory where tox.ini is located

    the directory where virtual environments are created and sub directories
    for packaging reside.

    the user-home directory path.

    the directory where sdist-packages will be created in

    the directory where sdist-packages will be copied to so that
    they may be accessed by other processes or tox runs.

substitutions for virtualenv-related sections

    the name of the virtual environment
    path to the virtual Python interpreter
    directory of the virtualenv hierarchy
    directory where executables are located
    the environment temporary directory
    the environment log directory

environment variable substitutions

If you specify a substitution string like this::


then the value will be retrieved as ``os.environ['KEY']``
and raise an Error if the environment variable
does not exist.

.. _`command positional substitution`:
.. _`positional substitution`:

substitutions for positional arguments in commands

.. versionadded:: 1.0

If you specify a substitution string like this::


then the value will be replaced with positional arguments as provided
to the tox command::

    tox arg1 arg2

In this instance, the positional argument portion will be replaced with
``arg1 arg2``. If no positional arguments were specified, the value of
DEFAULTS will be used instead. If DEFAULTS contains other substitution
strings, such as ``{env:*}``, they will be interpreted.,

Use a double ``--`` if you also want to pass options to an underlying
test command, for example::

    tox -- --opt1 ARG1

will make the ``--opt1 ARG1`` appear in all test commands where ``[]`` or
``{posargs}`` was specified.  By default (see ``args_are_paths``
setting), ``tox`` rewrites each positional argument if it is a relative
path and exists on the filesystem to become a path relative to the
``changedir`` setting.

Previous versions of tox supported the ``[.*]`` pattern to denote
positional arguments with defaults. This format has been deprecated.
Use ``{posargs:DEFAULTS}`` to specify those.

Substition for values from other sections

.. versionadded:: 1.4

Values from other sections can be refered to via::


which you can use to avoid repetition of config values.
You can put default values in one section and reference them in others to avoid repeting the same values::

    deps =
    deps =

    dep =

Other Rules and notes

* ``path`` specifications: if a specified ``path`` is a relative path
  it will be considered as relative to the ``toxinidir``, the directory
  where the configuration file resides.

.. include:: links.txt