diff options
Diffstat (limited to 'doc/config.txt')
| -rw-r--r-- | doc/config.txt | 633 |
1 files changed, 0 insertions, 633 deletions
diff --git a/doc/config.txt b/doc/config.txt deleted file mode 100644 index d99e91c..0000000 --- a/doc/config.txt +++ /dev/null @@ -1,633 +0,0 @@ -.. be in -*- rst -*- mode! - -tox configuration specification -=============================== - -.. _ConfigParser: http://docs.python.org/library/configparser.html - -``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:: - - [tox] - 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 # (DEPRECATED) defaults to {homedir}/.tox/distshare - envlist=ENVLIST # defaults to the list of all environments - skipsdist=BOOL # defaults to false - - -``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:: - - [tox:jenkins] - ... # override [tox] settings for the jenkins context - # note: for jenkins distshare defaults to ``{toxworkdir}/distshare`` (DEPRECATED) - -.. confval:: skip_missing_interpreters=BOOL - - .. versionadded:: 1.7.2 - - Setting this to ``True`` is equivalent of passing the - ``--skip-missing-interpreters`` command line option, and will force ``tox`` to - return success even if some of the specified environments were missing. This is - useful for some CI systems or running on a developer box, where you might only - have a subset of all your supported interpreters installed but don't want to - mark the build as failed because of it. As expected, the command line switch - always overrides this setting if passed on the invokation. - **Default:** ``False`` - -.. confval:: envlist=CSV - - Determining the environment list that ``tox`` is to operate on - happens in this order (if any is found, no further lookups are made): - - * command line option ``-eENVLIST`` - * environment variable ``TOXENV`` - * ``tox.ini`` file's ``envlist`` - - -Virtualenv test environment settings ------------------------------------- - -Test environments are defined by a:: - - [testenv:NAME] - ... - -section. The ``NAME`` will be the name of the virtual environment. -Defaults for each setting in this section are looked up in the:: - - [testenv] - ... - -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. - Similar to ``make`` recipe lines, any command with a leading ``-`` - will ignore the exit code. - -.. confval:: install_command=ARGV - - .. versionadded:: 1.6 - - the ``install_command`` setting is used for installing packages into - the virtual environment; both the package under test - and any defined dependencies. Must contain the substitution key - ``{packages}`` which will be replaced by the packages to - install. You should also accept ``{opts}`` if you are using - pip or easy_install -- it will contain index server options - if you have configured them via :confval:`indexserver` - and the deprecated :confval:`downloadcache` option - if you have configured it. - - **default**:: - - pip install {opts} {packages} - - -.. confval:: list_dependencies_command - - .. versionadded:: 2.4 - - the ``list_dependencies_command`` setting is used for listing - the packages installed into the virtual environment. - - **default**:: - - pip freeze - - -.. confval:: ignore_errors=True|False(default) - - .. versionadded:: 2.0 - - If ``True``, a non-zero exit code from one command will be ignored and - further commands will be executed (which was the default behavior in tox < - 2.0). If ``False`` (the default), then a non-zero exit code from one command - will abort execution of commands for that environment. - - It may be helpful to note that this setting is analogous to the ``-i`` or - ``ignore-errors`` option of GNU Make. A similar name was chosen to reflect the - similarity in function. - - Note that in tox 2.0, the default behavior of tox with respect to - treating errors from commands changed. Tox < 2.0 would ignore errors by - default. Tox >= 2.0 will abort on an error by default, which is safer and more - typical of CI and command execution tools, as it doesn't make sense to - run tests if installing some prerequisite failed and it doesn't make sense to - try to deploy if tests failed. - -.. confval:: pip_pre=True|False(default) - - .. versionadded:: 1.9 - - If ``True``, adds ``--pre`` to the ``opts`` passed to - :confval:`install_command`. If :confval:`install_command` uses pip, this - will cause it to install the latest available pre-release of any - dependencies without a specified version. If ``False`` (the default), pip - will only install final releases of unpinned dependencies. - - Passing the ``--pre`` command-line option to tox will force this to - ``True`` for all testenvs. - - Don't set this option if your :confval:`install_command` does not use pip. - -.. confval:: whitelist_externals=MULTI-LINE-LIST - - each line specifies a command name (in glob-style pattern format) - which can be used in the ``commands`` section without triggering - a "not installed in virtualenv" warning. Example: if you use the - unix ``make`` for running tests you can list ``whitelist_externals=make`` - or ``whitelist_externals=/usr/bin/make`` if you want more precision. - If you don't want tox to issue a warning in any case, just use - ``whitelist_externals=*`` which will match all commands (not recommended). - -.. confval:: changedir=path - - change to this working directory when executing the test command. - **default**: ``{toxinidir}`` - -.. confval:: deps=MULTI-LINE-LIST - - test-specific dependencies - to be installed into the environment prior to project - package installation. Each line defines a dependency, which will be - passed to the installer command for processing. Each line specifies a file, - a URL or a package name. You can additionally specify - an :confval:`indexserver` to use for installing this dependency - but this functionality is deprecated since tox-2.3. - All derived dependencies (deps required by the dep) will then be - retrieved from the specified indexserver:: - - deps = :myindexserver:pkg - - (Experimentally introduced in 1.6.1) all installer commands are executed - using the ``{toxinidir}`` as the current working directory. - -.. confval:: platform=REGEX - - A testenv can define a new ``platform`` setting as a regular expression. - If a non-empty expression is defined and does not match against the - ``sys.platform`` string the test environment will be skipped. - -.. 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:: passenv=SPACE-SEPARATED-GLOBNAMES - - .. versionadded:: 2.0 - - A list of wildcard environment variable names which - shall be copied from the tox invocation environment to the test - environment when executing test commands. If a specified environment - variable doesn't exist in the tox invocation environment it is ignored. - You can use ``*`` and ``?`` to match multiple environment variables with - one name. - - Note that the ``PATH``, ``LANG`` and ``PIP_INDEX_URL`` variables are - unconditionally passed down and on Windows ``SYSTEMROOT``, ``PATHEXT``, - ``TEMP`` and ``TMP`` will be passed down as well whereas on unix - ``TMPDIR`` will be passed down. You can override these variables - with the ``setenv`` option. - - If defined the ``TOX_TESTENV_PASSENV`` environment variable (in the tox - invocation environment) can define additional space-separated variable - names that are to be passed down to the test command environment. - -.. confval:: recreate=True|False(default) - - Always recreate virtual environment if this option is True. - -.. confval:: downloadcache=path - - **DEPRECATED** -- as of August 2013 this option is not very - useful because of pypi's CDN and because of caching pypi - server solutions like `devpi <http://doc.devpi.net>`_. - - use this directory for caching downloads. This value is overriden - by the environment variable ``PIP_DOWNLOAD_CACHE`` if it exists. If - you specify a custom :confval:`install_command` that uses an - installer other than pip, your installer must support the - `--download-cache` command-line option. - **default**: no download cache will be used. - -.. 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 without inheriting the global site packages. - -.. 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 - invocation. - **default**: ``{envdir}/log`` - -.. confval:: indexserver - - .. versionadded:: 0.9 - - (DEPRECATED, will be removed in a future version) Multi-line ``name = - URL`` definitions of python package servers. Dependencies 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:: - - [tox] - indexserver = - default = http://mypypi.org - - will make tox install all dependencies from this PYPI index server - (including when installing the project sdist package). - - -.. confval:: envdir - - .. versionadded:: 1.5 - - User can set specific path for environment. If path would not be absolute it - would be treated as relative to ``{toxinidir}``. **default**: - ``{toxworkdir}/{envname}`` - -.. confval:: usedevelop=BOOL - - .. versionadded:: 1.6 - - Install the current package in development mode with "setup.py - develop" instead of installing from the ``sdist`` package. (This - uses pip's `-e` option, so should be avoided if you've specified a - custom :confval:`install_command` that does not support ``-e``). - - **default**: ``False`` - -.. confval:: skip_install=BOOL - - .. versionadded:: 1.9 - - Do not install the current package. This can be used when you need the - virtualenv management but do not want to install the current package - into that environment. - - **default**: ``False`` - -.. confval:: ignore_outcome=BOOL - - .. versionadded:: 2.2 - - If set to True a failing result of this testenv will not make tox fail, - only a warning will be produced. - - **default**: ``False`` - - -Substitutions -------------- - -Any ``key=value`` setting in an ini-file can make use -of value substitution through the ``{...}`` string-substitution pattern. - -You can escape curly braces with the ``\`` character if you need them, for example:: - - commands = echo "\{posargs\}" = {posargs} - -Globally available substitutions -++++++++++++++++++++++++++++++++ - -``{toxinidir}`` - the directory where tox.ini is located - -``{toxworkdir}`` - the directory where virtual environments are created and sub directories - for packaging reside. - -``{homedir}`` - the user-home directory path. - -``{distdir}`` - the directory where sdist-packages will be created in - -``{distshare}`` - (DEPRECATED) 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 -+++++++++++++++++++++++++++++++++++++++++++++ - -``{envname}`` - the name of the virtual environment -``{envpython}`` - path to the virtual Python interpreter -``{envdir}`` - directory of the virtualenv hierarchy -``{envbindir}`` - directory where executables are located -``{envsitepackagesdir}`` - directory where packages are installed. - Note that architecture-specific files may appear in a different directory. -``{envtmpdir}`` - the environment temporary directory -``{envlogdir}`` - the environment log directory - - -environment variable substitutions -++++++++++++++++++++++++++++++++++ - -If you specify a substitution string like this:: - - {env:KEY} - -then the value will be retrieved as ``os.environ['KEY']`` -and raise an Error if the environment variable -does not exist. - - -environment variable substitutions with default values -++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -If you specify a substitution string like this:: - - {env:KEY:DEFAULTVALUE} - -then the value will be retrieved as ``os.environ['KEY']`` -and replace with DEFAULTVALUE if the environment variable does not -exist. - -If you specify a substitution string like this:: - - {env:KEY:} - -then the value will be retrieved as ``os.environ['KEY']`` -and replace with and empty string 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:: - - {posargs:DEFAULTS} - -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. - - -Substitution for values from other sections -+++++++++++++++++++++++++++++++++++++++++++ - -.. versionadded:: 1.4 - -Values from other sections can be refered to via:: - - {[sectionname]valuename} - -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 repeating the same values:: - - [base] - deps = - pytest - mock - pytest-xdist - - [testenv:dulwich] - deps = - dulwich - {[base]deps} - - [testenv:mercurial] - deps = - mercurial - {[base]deps} - - -Generating environments, conditional settings ---------------------------------------------- - -.. versionadded:: 1.8 - -Suppose you want to test your package against python2.6, python2.7 and against -several versions of a dependency, say Django 1.5 and Django 1.6. You can -accomplish that by writing down 2*2 = 4 ``[testenv:*]`` sections and then -listing all of them in ``envlist``. - -However, a better approach looks like this:: - - [tox] - envlist = {py26,py27}-django{15,16} - - [testenv] - basepython = - py26: python2.6 - py27: python2.7 - deps = - pytest - django15: Django>=1.5,<1.6 - django16: Django>=1.6,<1.7 - py26: unittest2 - commands = py.test - -This uses two new facilities of tox-1.8: - -- generative envlist declarations where each envname - consists of environment parts or "factors" - -- "factor" specific settings - -Let's go through this step by step. - - -.. _generative-envlist: - -Generative envlist -+++++++++++++++++++++++ - -:: - - envlist = {py26,py27}-django{15,16} - -This is bash-style syntax and will create ``2*2=4`` environment names -like this:: - - py26-django15 - py26-django16 - py27-django15 - py27-django16 - -You can still list environments explicitly along with generated ones:: - - envlist = {py26,py27}-django{15,16}, docs, flake - -.. note:: - - To help with understanding how the variants will produce section values, - you can ask tox to show their expansion with a new option:: - - $ tox -l - py26-django15 - py26-django16 - py27-django15 - py27-django16 - docs - flake - - -.. _factors: - -Factors and factor-conditional settings -++++++++++++++++++++++++++++++++++++++++ - -Parts of an environment name delimited by hyphens are called factors and can -be used to set values conditionally:: - - basepython = - py26: python2.6 - py27: python2.7 - -This conditional setting will lead to either ``python2.6`` or -``python2.7`` used as base python, e.g. ``python2.6`` is selected if current -environment contains ``py26`` factor. - -In list settings such as ``deps`` or ``commands`` you can freely intermix -optional lines with unconditional ones:: - - deps = - pytest - django15: Django>=1.5,<1.6 - django16: Django>=1.6,<1.7 - py26: unittest2 - -Reading it line by line: - -- ``pytest`` will be included unconditionally, -- ``Django>=1.5,<1.6`` will be included for environments containing ``django15`` factor, -- ``Django>=1.6,<1.7`` similarly depends on ``django16`` factor, -- ``unittest`` will be loaded for Python 2.6 environments. - -.. note:: - - Tox provides good defaults for basepython setting, so the above - ini-file can be further reduced by omitting the ``basepython`` - setting. - - -Complex factor conditions -+++++++++++++++++++++++++ - -Sometimes you need to specify the same line for several factors or create a -special case for a combination of factors. Here is how you do it:: - - [tox] - envlist = py{26,27,33}-django{15,16}-{sqlite,mysql} - - [testenv] - deps = - py33-mysql: PyMySQL ; use if both py33 and mysql are in an env name - py26,py27: urllib3 ; use if any of py26 or py27 are in an env name - py{26,27}-sqlite: mock ; mocking sqlite in python 2.x - -Take a look at first ``deps`` line. It shows how you can special case something -for a combination of factors, you just join combining factors with a hyphen. -This particular line states that ``PyMySQL`` will be loaded for python 3.3, -mysql environments, e.g. ``py33-django15-mysql`` and ``py33-django16-mysql``. - -The second line shows how you use same line for several factors - by listing -them delimited by commas. It's possible to list not only simple factors, but -also their combinations like ``py26-sqlite,py27-sqlite``. - -Finally, factor expressions are expanded the same way as envlist, so last -example could be rewritten as ``py{26,27}-sqlite``. - -.. note:: - - Factors don't do substring matching against env name, instead every - hyphenated expression is split by ``-`` and if ALL the factors in an - expression are also factors of an env then that condition is considered - hold. - - For example, environment ``py26-mysql``: - - - could be matched with expressions ``py26``, ``py26-mysql``, - ``mysql-py26``, - - but not with ``py2`` or ``py26-sql``. - - -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 |