diff options
author | Alexander Schepanovski <suor.web@gmail.com> | 2014-07-17 15:12:02 +0800 |
---|---|---|
committer | Alexander Schepanovski <suor.web@gmail.com> | 2014-07-17 15:12:02 +0800 |
commit | 1135a2a07207907db8cd24bd6bd5407fa1fe902f (patch) | |
tree | 98394788ff77f36950b3c2d9c9a6009ff065a60b /doc/config.txt | |
parent | fa48190fed81c28e393c162ef7189b7cc1f62332 (diff) | |
download | tox-1135a2a07207907db8cd24bd6bd5407fa1fe902f.tar.gz |
Docs on factors and envlist expansion
Diffstat (limited to 'doc/config.txt')
-rw-r--r-- | doc/config.txt | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/doc/config.txt b/doc/config.txt index 9288ee2..8837664 100644 --- a/doc/config.txt +++ b/doc/config.txt @@ -382,6 +382,115 @@ You can put default values in one section and reference them in others to avoid {[base]deps} +Generating environments and selecting factors +--------------------------------------------- + +.. 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 would be generating ``envlist`` and then selecting +dependencies this way:: + + [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 + !py27: unittest2 + commands = py.test + +Let's go through this step by step. + + +Generating environments ++++++++++++++++++++++++ + +:: + + 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 explicit environments along with generated ones:: + + envlist = {py26,py27}-django{15,16}, docs, flake + + +Factors ++++++++ + +A parts of environment names delimited by hyphens are called factors and could +be used to alter values of ``[testenv]`` settings:: + + 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 + !py27: unittest2 + +A last line here uses negation of a factor, this means ``unittest2`` will be +in ``deps`` for all pythons except python2.7. The whole effect of this setting +definition could be described with a table: + +=============== ================================== +environment deps +=============== ================================== +py26-django15 pytest, Django>=1.5,<1.6, unitest2 +py26-django16 pytest, Django>=1.6,<1.7, unitest2 +py27-django15 pytest, Django>=1.5,<1.6 +py27-django16 pytest, Django>=1.6,<1.7 +=============== ================================== + +And this table can significantly grow as you have more dependencies and other +factors such as platform, python version and/or database. + +.. note:: + + Tox provides good defaults for basepython setting, so the above ini-file can be + further reduced by omitting it. + + +Showing all expanded sections ++++++++++++++++++++++++++++++ + +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 + Other Rules and notes ===================== |