diff options
Diffstat (limited to 'doc')
37 files changed, 0 insertions, 3989 deletions
diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index aae1962..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,140 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -SITETARGET=$(shell ./_getdoctarget.py) - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - - -install: clean html - @rsync -avz $(BUILDDIR)/html/ testrun.org:/www/testrun.org/tox/latest - @rsync -avz $(BUILDDIR)/html/ testrun.org:/www/testrun.org/tox/$(SITETARGET) - #dev - #latexpdf - #@scp $(BUILDDIR)/latex/*.pdf testrun.org:www-tox/latest - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/tox.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/tox.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/tox" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/tox" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/_getdoctarget.py b/doc/_getdoctarget.py deleted file mode 100755 index f92e87b..0000000 --- a/doc/_getdoctarget.py +++ /dev/null @@ -1,16 +0,0 @@ -#!/usr/bin/env python - -import py - -def get_version_string(): - fn = py.path.local(__file__).join("..", "..", - "tox", "__init__.py") - for line in fn.readlines(): - if "version" in line and not line.strip().startswith('#'): - return eval(line.split("=")[-1]) - -def get_minor_version_string(): - return ".".join(get_version_string().split(".")[:2]) - -if __name__ == "__main__": - print(get_minor_version_string()) diff --git a/doc/_static/sphinxdoc.css b/doc/_static/sphinxdoc.css deleted file mode 100644 index ab8ab5d..0000000 --- a/doc/_static/sphinxdoc.css +++ /dev/null @@ -1,339 +0,0 @@ -/* - * sphinxdoc.css_t - * ~~~~~~~~~~~~~~~ - * - * Sphinx stylesheet -- sphinxdoc theme. Originally created by - * Armin Ronacher for Werkzeug. - * - * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. - * :license: BSD, see LICENSE for details. - * - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', - 'Verdana', sans-serif; - font-size: 1.1em; - letter-spacing: -0.01em; - line-height: 150%; - text-align: center; - background-color: #BFD1D4; - color: black; - padding: 0; - border: 1px solid #aaa; - - margin: 0px 80px 0px 80px; - min-width: 740px; -} - -div.document { - background-color: white; - text-align: left; - background-image: url(contents.png); - background-repeat: repeat-x; -} - -div.bodywrapper { - margin: 0 240px 0 0; - border-right: 1px solid #ccc; -} - -div.body { - margin: 0; - padding: 0.5em 20px 20px 20px; -} - -div.related { - font-size: 0.8em; -} - -div.related ul { - background-image: url(navigation.png); - height: 2em; - border-top: 1px solid #ddd; - border-bottom: 1px solid #ddd; -} - -div.related ul li { - margin: 0; - padding: 0; - height: 2em; - float: left; -} - -div.related ul li.right { - float: right; - margin-right: 5px; -} - -div.related ul li a { - margin: 0; - padding: 0 5px 0 5px; - line-height: 1.75em; - color: #EE9816; -} - -div.related ul li a:hover { - color: #3CA8E7; -} - -div.sphinxsidebarwrapper { - padding: 0; -} - -div.sphinxsidebar { - margin: 0; - padding: 0.5em 15px 15px 0; - width: 210px; - float: right; - font-size: 1em; - text-align: left; -} - -div.sphinxsidebar h3, div.sphinxsidebar h4 { - margin: 1em 0 0.5em 0; - font-size: 1em; - padding: 0.1em 0 0.1em 0.5em; - color: white; - border: 1px solid #86989B; - background-color: #AFC1C4; -} - -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar ul { - padding-left: 1.5em; - margin-top: 7px; - padding: 0; - line-height: 130%; -} - -div.sphinxsidebar ul ul { - margin-left: 20px; -} - -div.footer { - background-color: #E3EFF1; - color: #86989B; - padding: 3px 8px 3px 0; - clear: both; - font-size: 0.8em; - text-align: right; -} - -div.footer a { - color: #86989B; - text-decoration: underline; -} - -/* -- body styles ----------------------------------------------------------- */ - -p { - margin: 0.8em 0 0.5em 0; -} - -a { - color: #CA7900; - text-decoration: none; -} - -a:hover { - color: #2491CF; -} - -div.body a { - text-decoration: underline; -} - -h1 { - margin: 0; - padding: 0.7em 0 0.3em 0; - font-size: 1.5em; - color: #11557C; -} - -h2 { - margin: 1.3em 0 0.2em 0; - font-size: 1.35em; - padding: 0; -} - -h3 { - margin: 1em 0 -0.3em 0; - font-size: 1.2em; -} - -div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { - color: black!important; -} - -h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { - display: none; - margin: 0 0 0 0.3em; - padding: 0 0.2em 0 0.2em; - color: #aaa!important; -} - -h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, -h5:hover a.anchor, h6:hover a.anchor { - display: inline; -} - -h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, -h5 a.anchor:hover, h6 a.anchor:hover { - color: #777; - background-color: #eee; -} - -a.headerlink { - color: #c60f0f!important; - font-size: 1em; - margin-left: 6px; - padding: 0 4px 0 4px; - text-decoration: none!important; -} - -a.headerlink:hover { - background-color: #ccc; - color: white!important; -} - -cite, code, tt { - font-family: 'Consolas', 'Deja Vu Sans Mono', - 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.01em; -} - -tt { - background-color: #f2f2f2; - border-bottom: 1px solid #ddd; - color: #333; -} - -tt.descname, tt.descclassname, tt.xref { - border: 0; -} - -hr { - border: 1px solid #abc; - margin: 2em; -} - -a tt { - border: 0; - color: #CA7900; -} - -a tt:hover { - color: #2491CF; -} - -pre { - font-family: 'Consolas', 'Deja Vu Sans Mono', - 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.015em; - line-height: 120%; - padding: 0.5em; - border: 1px solid #ccc; - background-color: #f8f8f8; -} - -pre a { - color: inherit; - text-decoration: underline; -} - -td.linenos pre { - padding: 0.5em 0; -} - -div.quotebar { - background-color: #f8f8f8; - max-width: 250px; - float: right; - padding: 2px 7px; - border: 1px solid #ccc; -} - -div.topic { - background-color: #f8f8f8; -} - -table { - border-collapse: collapse; - margin: 0 -0.5em 0 -0.5em; -} - -table td, table th { - padding: 0.2em 0.5em 0.2em 0.5em; -} - -div.admonition, div.warning { - font-size: 0.9em; - margin: 1em 0 1em 0; - border: 1px solid #86989B; - background-color: #f7f7f7; - padding: 0; -} - -div.admonition p, div.warning p { - margin: 0.5em 1em 0.5em 1em; - padding: 0; -} - -div.admonition pre, div.warning pre { - margin: 0.4em 1em 0.4em 1em; -} - -div.admonition p.admonition-title, -div.warning p.admonition-title { - margin: 0; - padding: 0.1em 0 0.1em 0.5em; - color: white; - border-bottom: 1px solid #86989B; - font-weight: bold; - background-color: #AFC1C4; -} - -div.warning { - border: 1px solid #940000; -} - -div.warning p.admonition-title { - background-color: #CF0000; - border-bottom-color: #940000; -} - -div.admonition ul, div.admonition ol, -div.warning ul, div.warning ol { - margin: 0.1em 0.5em 0.5em 3em; - padding: 0; -} - -div.versioninfo { - margin: 1em 0 0 0; - border: 1px solid #ccc; - background-color: #DDEAF0; - padding: 8px; - line-height: 1.3em; - font-size: 0.9em; -} - -.viewcode-back { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', - 'Verdana', sans-serif; -} - -div.viewcode-block:target { - background-color: #f4debf; - border-top: 1px solid #ac9; - border-bottom: 1px solid #ac9; -} diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html deleted file mode 100644 index 12bf335..0000000 --- a/doc/_templates/indexsidebar.html +++ /dev/null @@ -1,21 +0,0 @@ -<h3>Download</h3> -{% if version.endswith('(hg)') %} -<p>This documentation is for version <b>{{ version }}</b>, which is - not released yet.</p> -<p>You can use it from the - <a href="http://code.google.com/p/pytox/source/checkout">Mercurial repo</a> or look for - released versions in the <a href="http://pypi.python.org/pypi/tox">Python - Package Index</a>.</p> -{% else %} -<p>Current: <b>{{ version }}</b> -[<a href="{{ pathto('changelog') }}">Changes</a>]</p> -<p> -<a href="http://pypi.python.org/pypi/tox">tox on PyPI</a> -</p> -<pre>pip install tox</pre> -{% endif %} - -<h3>Questions? Suggestions?</h3> - -<p>Checkout <a href="{{ pathto('support') }}">support channels</a> -</p> diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html deleted file mode 100644 index 1892483..0000000 --- a/doc/_templates/layout.html +++ /dev/null @@ -1,15 +0,0 @@ -{% extends "!layout.html" %} - - -{% block footer %} -{{ super() }} -<script type="text/javascript"> -var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); -document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); -</script> -<script type="text/javascript"> -try { -var pageTracker = _gat._getTracker("UA-17241637-3"); -pageTracker._trackPageview(); -} catch(err) {}</script> -{% endblock %} diff --git a/doc/_templates/localtoc.html b/doc/_templates/localtoc.html deleted file mode 100644 index 5976c4b..0000000 --- a/doc/_templates/localtoc.html +++ /dev/null @@ -1,36 +0,0 @@ - -{%- if pagename != "search" %} -<div id="searchbox" style="display: none"> - <form class="search" action="{{ pathto('search') }}" method="get"> - <input type="text" name="q" size="18" /> - <input type="submit" value="{{ _('Search') }}" /> - <input type="hidden" name="check_keywords" value="yes" /> - <input type="hidden" name="area" value="default" /> - </form> -</div> -<script type="text/javascript">$('#searchbox').show(0);</script> -{%- endif %} - -<h3>quicklinks</h3> -<div style="text-align: left; font-size: 100%; vertical-align: middle;"> -<table> -<tr> -<td> - <a href="{{ pathto('index') }}">home</a> -</td><td> - <a href="{{ pathto('examples') }}">examples</a> -</td></tr><tr><td> - <a href="{{ pathto('install') }}">install</a> -</td><td> - <a href="{{ pathto('changelog') }}">changelog</a> -</td></tr><tr><td> - <a href="{{ pathto('config') }}">config</a> -</td><td> - <a href="https://bitbucket.org/hpk42/tox/issues?status=new&status=open">issues[bb]</a> -</td></tr><tr><td> - <a href="{{ pathto('support') }}">support</a> -</td><td> -</td></tr></table> -</div> -{% extends "basic/localtoc.html" %} - diff --git a/doc/announce/release-0.5.txt b/doc/announce/release-0.5.txt deleted file mode 100644 index f4c30eb..0000000 --- a/doc/announce/release-0.5.txt +++ /dev/null @@ -1,26 +0,0 @@ -tox 0.5: a generic virtualenv and test management tool for Python -=========================================================================== - -I have been talking about with various people in the last year and -am happy to now announce the first release of ``tox``. It aims -to automate tedious Python related test activities driven -from a simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments -* installing your package into each of them -* running your test tool of choice (including e.g. running sphinx checks) -* testing packages against each other without needing to upload to PyPI - -``tox`` runs well on Python2.4 up until Python3.1 and integrates -well with Continuous Integration servers Jenkins. There are many -real-life examples and a good chunk of docs. Read it up on - - http://codespeak.net/tox - -and please report any issues. This is a fresh project and -i'd like to drive further improvements from real world needs. - -best, - -holger krekel - diff --git a/doc/announce/release-1.0.txt b/doc/announce/release-1.0.txt deleted file mode 100644 index ae46d41..0000000 --- a/doc/announce/release-1.0.txt +++ /dev/null @@ -1,55 +0,0 @@ -tox 1.0: the rapid multi-python test automatizer -=========================================================================== - -I am happy to announce tox 1.0, mostly a stabilization and streamlined -release. TOX automates tedious test activities driven from a -simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments with - different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or - other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -Docs and examples are at: - - http://tox.readthedocs.org - -Installation: - - pip install -U tox - -Note that code hosting and issue tracking has moved from Google to Bitbucket: - - https://bitbucket.org/hpk42/tox - -The 1.0 release includes contributions and is based on feedback and -work from Chris Rose, Ronny Pfannschmidt, Jannis Leidel, Jakob Kaplan-Moss, -Sridhar Ratnakumar, Carl Meyer and others. Many thanks! - -best, -Holger Krekel - -CHANGES ---------------------- - -- fix issue24: introduce a way to set environment variables for - for test commands (thanks Chris Rose) -- fix issue22: require virtualenv-1.6.1, obsoleting virtualenv5 (thanks Jannis Leidel) - and making things work with pypy-1.5 and python3 more seemlessly -- toxbootstrap.py (used by jenkins build slaves) now follows the latest release of virtualenv -- fix issue20: document format of URLs for specifying dependencies -- fix issue19: substitute Hudson for Jenkins everywhere following the renaming - of the project. NOTE: if you used the special [tox:hudson] - section it will now need to be named [tox:jenkins]. -- fix issue 23 / apply some ReST fixes -- change the positional argument specifier to use {posargs:} syntax and - fix issues #15 and #10 by refining the argument parsing method (Chris Rose) -- remove use of inipkg lazy importing logic - - the namespace/imports are anyway very small with tox. -- fix a fspath related assertion to work with debian installs which uses - symlinks -- show path of the underlying virtualenv invocation and bootstrap - virtualenv.py into a working subdir -- added a CONTRIBUTORS file diff --git a/doc/announce/release-1.1.txt b/doc/announce/release-1.1.txt deleted file mode 100644 index 8ab78db..0000000 --- a/doc/announce/release-1.1.txt +++ /dev/null @@ -1,50 +0,0 @@ -tox 1.1: the rapid multi-python test automatizer -=========================================================================== - -I am happy to announce tox 1.1, a bug fix release easing some commong -workflows. TOX automates tedious test activities driven from a simple -``tox.ini`` file, including: - -* creation and management of different virtualenv environments with - different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or - other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -It works well on virtually all Python interpreters that support virtualenv. - -Docs and examples are at: - - http://tox.readthedocs.org - -Installation: - - pip install -U tox - -Note that code hosting and issue tracking has moved from Google to Bitbucket: - - https://bitbucket.org/hpk42/tox - -The 1.0 release includes contributions and is based on feedback and -work from Chris Rose, Ronny Pfannschmidt, Jannis Leidel, Jakob Kaplan-Moss, -Sridhar Ratnakumar, Carl Meyer and others. Many thanks! - -best, -Holger Krekel - -CHANGES ---------------------- - -- fix issue5 - don't require argparse for python versions that have it -- fix issue6 - recreate virtualenv if installing dependencies failed -- fix issue3 - fix example on frontpage -- fix issue2 - warn if a test command does not come from the test - environment -- fixed/enhanced: except for initial install always call "-U - --no-deps" for installing the sdist package to ensure that a package - gets upgraded even if its version number did not change. (reported on - TIP mailing list and IRC) -- inline virtualenv.py (1.6.1) script to avoid a number of issues, - particularly failing to install python3 environents from a python2 - virtualenv installation. diff --git a/doc/announce/release-1.2.txt b/doc/announce/release-1.2.txt deleted file mode 100644 index 139d812..0000000 --- a/doc/announce/release-1.2.txt +++ /dev/null @@ -1,42 +0,0 @@ -tox 1.2: the virtualenv-based test run automatizer -=========================================================================== - -I am happy to announce tox 1.2, now using and depending on the latest -virtualenv code and containing some bug fixes. TOX automates tedious -test activities driven from a simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments with - different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or - other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -It works well on virtually all Python interpreters that support virtualenv. - -Docs and examples are at: - - http://tox.testrun.org/ - -Installation: - - pip install -U tox - -code hosting and issue tracking on bitbucket: - - https://bitbucket.org/hpk42/tox - -best, -Holger Krekel - -1.2 compared to 1.1 ---------------------- - -- remove the virtualenv.py that was distributed with tox and depend - on virtualenv-1.6.4 (possible now since the latter fixes a few bugs - that the inling tried to work around) -- fix issue10: work around UnicodeDecodeError when inokving pip (thanks - Marc Abramowitz) -- fix a problem with parsing {posargs} in tox commands (spotted by goodwill) -- fix the warning check for commands to be installed in testevironment - (thanks Michael Foord for reporting) diff --git a/doc/announce/release-1.3.txt b/doc/announce/release-1.3.txt deleted file mode 100644 index b88fc39..0000000 --- a/doc/announce/release-1.3.txt +++ /dev/null @@ -1,41 +0,0 @@ -tox 1.3: the virtualenv-based test run automatizer -=========================================================================== - -I am happy to announce tox 1.3, containing a few improvements -over 1.2. TOX automates tedious test activities driven from a -simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments - with different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -Docs and examples are at: - - http://tox.testrun.org/ - -Installation: - - pip install -U tox - -code hosting and issue tracking on bitbucket: - - https://bitbucket.org/hpk42/tox - -best, -Holger Krekel - -1.3 ------------------ - -- fix: allow to specify wildcard filesystem paths when - specifiying dependencies such that tox searches for - the highest version - -- fix issue issue21: clear PIP_REQUIRES_VIRTUALENV which avoids - pip installing to the wrong environment, thanks to bb's streeter - -- make the install step honour a testenv's setenv setting - (thanks Ralf Schmitt) - diff --git a/doc/announce/release-1.4.3.txt b/doc/announce/release-1.4.3.txt deleted file mode 100644 index ca0bb19..0000000 --- a/doc/announce/release-1.4.3.txt +++ /dev/null @@ -1,97 +0,0 @@ -tox 1.4.3: the Python virtualenv-based testing automatizer -============================================================================= - -tox 1.4.3 fixes some bugs and introduces a new script and two new options: - -- "tox-quickstart" - run this script, answer a few questions, and - get a tox.ini created for you (thanks Marc Abramowitz) - -- "tox -l" lists configured environment names (thanks Lukasz Balcerzak) - -- (experimental) "--installpkg=localpath" option which will skip the - sdist-creation of a package and instead install the given localpath package. - -- use pip-script.py instead of pip.exe on win32 to avoid windows locking - the .exe - -Note that the sister project "detox" should continue to work - it's a -separately released project which drives tox test runs on multiple CPUs -in parallel. - -More documentation: - - http://tox.testrun.org/ - -Installation: - - pip install -U tox - -repository hosting and issue tracking on bitbucket: - - https://bitbucket.org/hpk42/tox - - -What is tox? ----------------- - -tox standardizes and automates tedious python driven test activities -driven from a simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments - with different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -best, -Holger Krekel - - -CHANGELOG -================ - -1.4.3 (compared to 1.4.2) --------------------------------- - -- introduce -l|--listenv option to list configured environments - (thanks Lukasz Balcerzak) - -- fix downloadcache determination to work according to docs: Only - make pip use a download cache if PIP_DOWNLOAD_CACHE or a - downloadcache=PATH testenv setting is present. (The ENV setting - takes precedence) - -- fix issue84 - pypy on windows creates a bin not a scripts venv directory - (thanks Lukasz Balcerzak) - -- experimentally introduce --installpkg=PATH option to install a package rather than - create/install an sdist package. This will still require and use - tox.ini and tests from the current working dir (and not from the remote - package). - -- substitute {envsitepackagesdir} with the package installation directory (closes #72) - (thanks g2p) - -- issue #70 remove PYTHONDONTWRITEBYTECODE workaround now that - virtualenv behaves properly (thanks g2p) - -- merged tox-quickstart command, contributed by Marc Abramowitz, which - generates a default tox.ini after asking a few questions - -- fix #48 - win32 detection of pypy and other interpreters that are on PATH - (thanks Gustavo Picon) - -- fix grouping of index servers, it is now done by name instead of - indexserver url, allowing to use it to separate dependencies - into groups even if using the same default indexserver. - -- look for "tox.ini" files in parent dirs of current dir (closes #34) - -- the "py" environment now by default uses the current interpreter - (sys.executable) make tox' own setup.py test execute tests with it - (closes #46) - -- change tests to not rely on os.path.expanduser (closes #60), - also make mock session return args[1:] for more precise checking (closes #61) - thanks to Barry Warszaw for both. - diff --git a/doc/announce/release-1.4.txt b/doc/announce/release-1.4.txt deleted file mode 100644 index d0e6644..0000000 --- a/doc/announce/release-1.4.txt +++ /dev/null @@ -1,62 +0,0 @@ -tox 1.4: the virtualenv-based test run automatizer -============================================================================= - -I am happy to announce tox 1.4 which brings: - -- improvements with configuration file syntax, now allowing re-using - selected settings across config file sections. see http://testrun.org/tox/latest/config.html#substitution-for-values-from-other-sections - -- terminal reporting was simplified and streamlined. Now with - verbosity==0 (the default), less information will be shown - and you can use one or multiple "-v" options to increase verbosity. - -- internal re-organisation so that the separately released "detox" - tool can reuse tox code to implement a fully distributed tox run. - -More documentation: - - http://tox.testrun.org/ - -Installation: - - pip install -U tox - -code hosting and issue tracking on bitbucket: - - https://bitbucket.org/hpk42/tox - -What is tox? ----------------- - -tox standardizes and automates tedious test activities driven from a -simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments - with different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -best, -Holger Krekel - - -1.4 ------------------ - -- fix issue26 - no warnings on absolute or relative specified paths for commands -- fix issue33 - commentchars are ignored in key-value settings allowing - for specifying commands like: python -c "import sys ; print sys" - which would formerly raise irritating errors because the ";" - was considered a comment -- tweak and improve reporting -- refactor reporting and virtualenv manipulation - to be more accessible from 3rd party tools -- support value substitution from other sections - with the {[section]key} syntax -- fix issue29 - correctly point to pytest explanation - for importing modules fully qualified -- fix issue32 - use --system-site-packages and don't pass --no-site-packages -- add python3.3 to the default env list, so early adopters can test -- drop python2.4 support (you can still have your tests run on - python-2.4, just tox itself requires 2.5 or higher. diff --git a/doc/announce/release-1.8.txt b/doc/announce/release-1.8.txt deleted file mode 100644 index b8a2218..0000000 --- a/doc/announce/release-1.8.txt +++ /dev/null @@ -1,54 +0,0 @@ -tox 1.8: Generative/combinatorial environments specs -============================================================================= - -I am happy to announce tox 1.8 which implements parametrized environments. - -See https://tox.testrun.org/latest/config.html#generating-environments-conditional-settings -for examples and the new backward compatible syntax in your tox.ini file. - -Many thanks to Alexander Schepanovski for implementing and refining -it based on the specifcation draft. - -More documentation about tox in general: - - http://tox.testrun.org/ - -Installation: - - pip install -U tox - -code hosting and issue tracking on bitbucket: - - https://bitbucket.org/hpk42/tox - -What is tox? ----------------- - -tox standardizes and automates tedious test activities driven from a -simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments - with different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -best, -Holger Krekel, merlinux GmbH - - -Changes 1.8 (compared to 1.7.2) ---------------------------------------- - -- new multi-dimensional configuration support. Many thanks to - Alexander Schepanovski for the complete PR with docs. - And to Mike Bayer and others for testing and feedback. - -- fix issue148: remove "__PYVENV_LAUNCHER__" from os.environ when starting - subprocesses. Thanks Steven Myint. - -- fix issue152: set VIRTUAL_ENV when running test commands, - thanks Florian Ludwig. - -- better report if we can't get version_info from an interpreter - executable. Thanks Floris Bruynooghe. diff --git a/doc/announce/release-1.9.txt b/doc/announce/release-1.9.txt deleted file mode 100644 index 96379b9..0000000 --- a/doc/announce/release-1.9.txt +++ /dev/null @@ -1,66 +0,0 @@ -tox-1.9: refinements, fixes (+detox-0.9.4) -========================================== - -tox-1.9 was released to pypi, a maintenance release with mostly -backward-compatible enhancements and fixes. However, tox now defaults -to pip-installing only non-development releases and you have to set "pip_pre = -True" in your testenv section to have it install development ("pre") releases. - -In addition, there is a new detox-0.9.4 out which allow to run tox test -environments in parallel and fixes a compat problem with eventlet. - -Thanks to Alexander Schepanosvki, Florian Schulze and others for the -contributed fixes and improvements. - -More documentation about tox in general: - - http://tox.testrun.org/ - -Installation: - - pip install -U tox - -code hosting and issue tracking on bitbucket: - - https://bitbucket.org/hpk42/tox - -What is tox? ----------------- - -tox standardizes and automates tedious test activities driven from a -simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments - with different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -best, -Holger Krekel, merlinux GmbH - - -1.9.0 ------------ - -- fix issue193: Remove ``--pre`` from the default ``install_command``; by - default tox will now only install final releases from PyPI for unpinned - dependencies. Use ``pip_pre = true`` in a testenv or the ``--pre`` - command-line option to restore the previous behavior. - -- fix issue199: fill resultlog structure ahead of virtualenv creation - -- refine determination if we run from Jenkins, thanks Borge Lanes. - -- echo output to stdout when ``--report-json`` is used - -- fix issue11: add a ``skip_install`` per-testenv setting which - prevents the installation of a package. Thanks Julian Krause. - -- fix issue124: ignore command exit codes; when a command has a "-" prefix, - tox will ignore the exit code of that command - -- fix issue198: fix broken envlist settings, e.g. {py26,py27}{-lint,} - -- fix issue191: lessen factor-use checks - diff --git a/doc/announce/release-2.0.txt b/doc/announce/release-2.0.txt deleted file mode 100644 index e05af6c..0000000 --- a/doc/announce/release-2.0.txt +++ /dev/null @@ -1,111 +0,0 @@ -tox-2.0: plugins, platform, env isolation -========================================== - -tox-2.0 was released to pypi, a major new release with *mostly* -backward-compatible enhancements and fixes: - -- experimental support for plugins, see https://testrun.org/tox/latest/plugins.html - which includes also a refined internal registration mechanism for new testenv - ini options. You can now ask tox which testenv ini parameters exist - with ``tox --help-ini``. - -- ENV isolation: only pass through very few environment variables from the - tox invocation to the test environments. This may break test runs that - previously worked with tox-1.9 -- you need to either use the - ``setenv`` or ``passenv`` ini variables to set appropriate environment - variables. - -- PLATFORM support: you can set ``platform=REGEX`` in your testenv sections - which lets tox skip the environment if the REGEX does not match ``sys.platform``. - -- tox now stops execution of test commands if the first of them fails unless - you set ``ignore_errors=True``. - -Thanks to Volodymyr Vitvitski, Daniel Hahler, Marc Abramowitz, Anthon van -der Neuth and others for contributions. - -More documentation about tox in general: - - http://tox.testrun.org/ - -Installation: - - pip install -U tox - -code hosting and issue tracking on bitbucket: - - https://bitbucket.org/hpk42/tox - -What is tox? ----------------- - -tox standardizes and automates tedious test activities driven from a -simple ``tox.ini`` file, including: - -* creation and management of different virtualenv environments - with different Python interpreters -* packaging and installing your package into each of them -* running your test tool of choice, be it nose, py.test or unittest2 or other tools such as "sphinx" doc checks -* testing dev packages against each other without needing to upload to PyPI - -best, -Holger Krekel, merlinux GmbH - -2.0.0 ------------ - -- (new) introduce environment variable isolation: - tox now only passes the PATH and PIP_INDEX_URL variable from the tox - invocation environment to the test environment and on Windows - also ``SYSTEMROOT``, ``PATHEXT``, ``TEMP`` and ``TMP`` whereas - on unix additionally ``TMPDIR`` is passed. If you need to pass - through further environment variables you can use the new ``passenv`` setting, - a space-separated list of environment variable names. Each name - can make use of fnmatch-style glob patterns. All environment - variables which exist in the tox-invocation environment will be copied - to the test environment. - -- a new ``--help-ini`` option shows all possible testenv settings and - their defaults. - -- (new) introduce a way to specify on which platform a testenvironment is to - execute: the new per-venv "platform" setting allows to specify - a regular expression which is matched against sys.platform. - If platform is set and doesn't match the platform spec in the test - environment the test environment is ignored, no setup or tests are attempted. - -- (new) add per-venv "ignore_errors" setting, which defaults to False. - 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. - -- show and store in json the version dependency information for each venv - -- remove the long-deprecated "distribute" option as it has no effect these days. - -- fix issue233: avoid hanging with tox-setuptools integration example. Thanks simonb. - -- fix issue120: allow substitution for the commands section. Thanks - Volodymyr Vitvitski. - -- fix issue235: fix AttributeError with --installpkg. Thanks - Volodymyr Vitvitski. - -- tox has now somewhat pep8 clean code, thanks to Volodymyr Vitvitski. - -- fix issue240: allow to specify empty argument list without it being - rewritten to ".". Thanks Daniel Hahler. - -- introduce experimental (not much documented yet) plugin system - based on pytest's externalized "pluggy" system. - See tox/hookspecs.py for the current hooks. - -- introduce parser.add_testenv_attribute() to register an ini-variable - for testenv sections. Can be used from plugins through the - tox_add_option hook. - -- rename internal files -- tox offers no external API except for the - experimental plugin hooks, use tox internals at your own risk. - -- DEPRECATE distshare in documentation diff --git a/doc/changelog.txt b/doc/changelog.txt deleted file mode 100644 index 504f36c..0000000 --- a/doc/changelog.txt +++ /dev/null @@ -1,7 +0,0 @@ - -.. _changelog: - -Changelog history -================================= - -.. include:: ../CHANGELOG diff --git a/doc/check_sphinx.py b/doc/check_sphinx.py deleted file mode 100644 index 26f6b11..0000000 --- a/doc/check_sphinx.py +++ /dev/null @@ -1,17 +0,0 @@ -import py -import subprocess -def test_build_docs(tmpdir): - doctrees = tmpdir.join("doctrees") - htmldir = tmpdir.join("html") - subprocess.check_call([ - "sphinx-build", "-bhtml", - "-d", str(doctrees), ".", str(htmldir)]) - -def test_linkcheck(tmpdir): - doctrees = tmpdir.join("doctrees") - htmldir = tmpdir.join("html") - subprocess.check_call( - ["sphinx-build", "-blinkcheck", - "-d", str(doctrees), ".", str(htmldir)]) - - diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index 6094f60..0000000 --- a/doc/conf.py +++ /dev/null @@ -1,272 +0,0 @@ -# -*- coding: utf-8 -*- -# -# tox documentation build configuration file, created by -# sphinx-quickstart on Sat May 29 10:42:26 2010. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys, os - -# The short X.Y version. -sys.path.insert(0, os.path.dirname(__file__)) -import _getdoctarget - -version = _getdoctarget.get_minor_version_string() -release = _getdoctarget.get_version_string() - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.append(os.path.abspath('.')) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.txt' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'tox' -copyright = u'2015, holger krekel and others' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The full version, including alpha/beta/rc tags. - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. -html_theme = 'sphinxdoc' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {'index': 'indexsidebar.html'} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {'index': 'indexsidebar.html'} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -html_show_sourcelink = False - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'toxdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'a4' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '12pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'tox.tex', u'tox Documentation', - u'holger krekel', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'tox', u'tox Documentation', - [u'holger krekel'], 1) -] - - -# -- Options for Epub output --------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = u'tox' -epub_author = u'holger krekel' -epub_publisher = u'holger krekel' -epub_copyright = u'2010, holger krekel' - -# The language of the text. It defaults to the language option -# or en if the language is not set. -#epub_language = '' - -# The scheme of the identifier. Typical schemes are ISBN or URL. -#epub_scheme = '' - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -#epub_identifier = '' - -# A unique identification for the text. -#epub_uid = '' - -# HTML files that should be inserted before the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_pre_files = [] - -# HTML files shat should be inserted after the pages created by sphinx. -# The format is a list of tuples containing the path and title. -#epub_post_files = [] - -# A list of files that should not be packed into the epub file. -#epub_exclude_files = [] - -# The depth of the table of contents in toc.ncx. -#epub_tocdepth = 3 - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} - -def setup(app): - #from sphinx.ext.autodoc import cut_lines - #app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) - app.add_description_unit('confval', 'confval', - objname='configuration value', - indextemplate='pair: %s; configuration value') - - -linkcheck_timeout = 30 -linkcheck_ignore = [r'http://holgerkrekel.net'] diff --git a/doc/config-v2.txt b/doc/config-v2.txt deleted file mode 100644 index c639652..0000000 --- a/doc/config-v2.txt +++ /dev/null @@ -1,292 +0,0 @@ -V2: new tox multi-dimensional, platform-specific configuration --------------------------------------------------------------------- - -.. note:: - - This is a draft document sketching a to-be-done implementation. - It does not fully specify each change yet but should give a good - idea of where things are heading. For feedback, mail the - testing-in-python mailing list or open a pull request on - https://bitbucket.org/hpk42/tox/src/84d8cf3c2a95fefd874f22c8b2d257e94365472f/doc/config-v2.txt?at=default - -**Abstract**: Adding multi-dimensional configuration, platform-specification -and multiple installers to tox.ini. - -**Target audience**: Developers using or wanting to use tox for testing -their python projects. - -Issues with current tox (1.4) configuration ------------------------------------------------- - -Tox is used as a tool for creating and managing virtualenv environments -and running tests in them. As of tox-1.4 there are some issues frequently -coming up with its configuration language: - -- there is no way to instruct tox to parametrize testenv specifications - other than to list all combinations by specifying a ``[testenv:...]`` - section for each combination. Examples of real life situations - arising from this: - - * https://github.com/tomchristie/django-rest-framework/blob/b001a146d73348af18cfc4c943d87f2f389349c9/tox.ini - - * https://bitbucket.org/tabo/django-treebeard/src/93b579395a9c/tox.ini - -- there is no way to have platform specific settings other than to - define specific testenvs and invoke tox with a platform-specific - testenv list. - -- there is no way to specify the platforms against which a project - shall successfully run. - -- tox always uses pip for installing packages currently. This has - several issues: - - - no way to check if installing via easy_install works - - no installs of packages with compiled c-extensions (win32 standard) - - -Goals, resolving those issues ------------------------------------- - -This document discusses a possible solution for each of these issues, -namely these goals: - -- allow to more easily define and run dependency/interpreter variants - with testenvs -- allow platform-specific settings -- allow to specify platforms against which tests should run -- allow to run installer-variants (easy_install or pip, xxx) -- try to mimick/re-use bash-style syntax to ease learning curve. - - -Example: Generating and selecting variants ----------------------------------------------- - -Suppose you want to test your package against python2.6, python2.7 and on the -windows and linux platforms. Today you would have to -write down 2*2 = 4 ``[testenv:*]`` sections and then instruct -tox to run a specific list of environments on each platform. - -With tox-1.X you can directlys specify combinations:: - - # combination syntax gives 2 * 2 = 4 testenv names - # - envlist = {py26,py27}-{win,linux} - - [testenv] - deps = pytest - platform = - win: windows - linux: linux - basepython = - py26: python2.6 - py27: python2.7 - commands = py.test - -Let's go through this step by step:: - - envlist = {py26,py27}-{windows,linux} - -This is bash-style syntax and will create ``2*2=4`` environment names -like this:: - - py26-windows - py26-linux - py27-windows - py27-linux - -Our ``[testenv]`` uses a new templating style for the ``platform`` definition:: - - platform= - windows: windows - linux: linux - -These two conditional settings will lead to either ``windows`` or -``linux`` as the platform string. When the test environment is run, -its platform string needs to be contained in the string returned -from ``platform.platform()``. Otherwise the environment will be skipped. - -The next configuration item in the ``testenv`` section deals with -the python interpreter:: - - basepython = - py26: python2.6 - py27: python2.7 - -This defines a python executable, depending on if ``py26`` or ``py27`` -appears in the environment name. - -The last config item is simply the invocation of the test runner:: - - commands = py.test - -Nothing special here :) - -.. note:: - - Tox provides good defaults for platform and basepython - settings, so the above ini-file can be further reduced:: - - [tox] - envlist = {py26,py27}-{win,linux} - - [testenv] - deps = pytest - commands = py.test - - Voila, this multi-dimensional ``tox.ini`` configuration - defines 2*2=4 environments. - - -The new "platform" setting --------------------------------------- - -A testenv can define a new ``platform`` setting. If its value -is not contained in the string obtained from calling -``sys.platform`` the environment will be skipped. - -Expanding the ``envlist`` setting ----------------------------------------------------------- - -The new ``envlist`` setting allows to use ``{}`` bash-style -expressions. XXX explanation or pointer to bash-docs - -Templating based on environments names -------------------------------------------------- - -For a given environment name, all lines in a testenv section which -start with "NAME: ..." will be checked for being part in the environment -name. If they are part of it, the remainder will be the new line. -If they are not part of it, the whole line will be left out. -Parts of an environment name are obtained by ``-``-splitting it. - -Variant specification with [variant:VARNAME] - -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 [XXX output ommitted for now] - -Making sure your packages installs with easy_install ------------------------------------------------------- - -The new "installer" testenv setting allows to specify the tool for -installation in a given test environment:: - - [testenv] - installer = - easy: easy_install - pip: pip - -If you want to have your package installed with both easy_install -and pip, you can list them in your envlist likes this:: - - [tox] - envlist = py[26,27,32]-django[13,14]-[easy,pip] - -If no installer is specified, ``pip`` will be used. - -Default settings related to environments names/variants ---------------------------------------------------------------- - -tox comes with predefined settings for certain variants, namely: - -* ``{easy,pip}`` use easy_install or pip respectively -* ``{py24,py25,py26,py27,py31,py32,py33,py34,pypy19]`` use the respective - pythonNN or PyPy interpreter -* ``{win32,linux,darwin}`` defines the according ``platform``. - -You can use those in your “envlist” specification -without the need to define them yourself. - - -Use more bash-style syntax --------------------------------------- - -tox leverages bash-style syntax if you specify mintoxversion = 1.4: - -- $VARNAME or ${...} syntax instead of the older {} substitution. -- XXX go through config.txt and see how it would need to be changed - - -Transforming the examples: django-rest ------------------------------------------------- - -The original `django-rest-framework tox.ini -<https://github.com/tomchristie/django-rest-framework/blob/b001a146d73348af18cfc4c943d87f2f389349c9/tox.ini>`_ -file has 159 lines and a lot of repetition, the new one would +have 20 -lines and almost no repetition:: - - [tox] - envlist = {py25,py26,py27}-{django12,django13}{,-example} - - [testenv] - deps= - coverage==3.4 - unittest-xml-reporting==1.2 - Pyyaml==3.10 - django12: django==1.2.4 - django13: django==1.3.1 - # some more deps for running examples - example: wsgiref==0.1.2 - example: Pygments==1.4 - example: httplib2==0.6.0 - example: Markdown==2.0.3 - - commands = - !example: python setup.py test - example: python examples/runtests.py - - -Note that ``{,-example}`` in the envlist denotes two values, an empty -one and a ``example`` one. The empty value means that there are no specific -settings and thus no need to define a variant name. - -Transforming the examples: django-treebeard ------------------------------------------------- - -Another `tox.ini -<https://bitbucket.org/tabo/django-treebeard/raw/93b579395a9c/tox.ini>`_ -has 233 lines and runs tests against multiple Postgres and Mysql -engines. It also performs backend-specific test commands, passing -different command line options to the test script. With the new tox-1.X -we not only can do the same with 32 non-repetive configuration lines but -we also produce 36 specific testenvs with specific dependencies and test -commands:: - - [tox] - envlist = - {py24,py25,py26,py27}-{django11,django12,django13}-{nodb,pg,mysql}, docs - - [testenv:docs] - changedir = docs - deps = - Sphinx - Django - commands = - make clean - make html - - [testenv] - deps= - coverage - pysqlite - django11: django==1.1.4 - django12: django==1.2.7 - django13: django==1.3.1 - django14: django==1.4 - nodb: pysqlite - pg: psycopg2 - mysql: MySQL-python - - commands = - nodb: {envpython} runtests.py {posargs} - pg: {envpython} runtests.py {posargs} \ - --DATABASE_ENGINE=postgresql_psycopg2 \ - --DATABASE_USER=postgres {posargs} - mysql: {envpython} runtests.py --DATABASE_ENGINE=mysql \ - --DATABASE_USER=root {posargs} - 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 diff --git a/doc/drafts/extend-envs-and-packagebuilds.md b/doc/drafts/extend-envs-and-packagebuilds.md deleted file mode 100644 index b2cdc0e..0000000 --- a/doc/drafts/extend-envs-and-packagebuilds.md +++ /dev/null @@ -1,155 +0,0 @@ -# Extension of environment handling and building packages - -Issue reference: #338 - -*Notes from a discussion at the pytest sprint 2016* - -Goal: drive building of packages and the environments needed to test them, exercising the tests and report the results for more than just virtualenvs and python virtualenvs - -### Problems - -* No concept of mapping environments to specific packages (versioned packages) -* no control over when it happens for specific environment -* no control over how it happens (e.g. which python interpreter is used to create the package) -* No way of triggering build only if there is an environment that needs a specific build trigger it only if an environment actually needs it -* package definition that might match on everything might be a problem for which environments test? Not clear? - -### Solution - -It should be possible to build other kinds of packages than just the standard sdist and it should also be possible to create different kinds of builds that can be used from different environments. To make this possible there has to be some concept of factorized package definitions and a way to match these factorized builds to environments with a similar way of matching like what is in place already to generate environments. sdist would for example would match to a "sdist" factor to only be matched against virtualenvs as the default. - -This could then be used to hae virtualenv, conda, nixos, docker, pyenv, rpm, deb, etc. builds and tie them to concrete test environments. - -To summarize - we would need a: - - * packagedef (how to build a package) - * envdef (how to build an environment) - * way of matching envs to concrete packages (at package definition level) (e.g `{py27,py34}-{win32,linux}-{venv,conda,pyenv}-[...]`) - -## Beginnings of configuration examples (not thought out yet) - - [tox] - envlist={py,27,py34}-{win32, linux}-{conda,virtualenv} - - [packagedef:sdist] - # how to build (e.g. {py27,py34}-{sdist}) - # how to match (e.g. {py27,py34}-{sdist}) - - [packagedef:conda] - # how to build (e.g. {py27,py34}-{conda}) - # how to match (e.g. {py27,py34}-{conda}) - - [packagedef:wheel] - # how to build - # how to match - -#### integrate detox - -* reporting in detox is minimal (would need to improve) -* restricting processes would be necessary depending on power of the machine - (creating 16 processe on a dual core machine might be overkill) -* port it from eventlets to threads? - -### Concrete use case conda integration (started by Bruno) - -* Asynchronicity / detox not taken into account yet -* Conda activation might do anything (change filesys, start DBs) -* Can I activate environments in parallel -* Packages would need to be created (from conda.yml) -* Activation is a problem - - -### Unsorted discussion notes - -* Simplify for the common case: most packages are universal, so it should be simple -one to one relationship from environment to directory -* Floris: metadata driven. Package has metadata to the env with what env it is compatible -* Holger: configuration driven. explicitly configuring which packages should be used (default sdist to be used, overridable by concrete env) -* Ronny: "package definitions" (this package, this setup command) + matching definitions (matching packages (with wildcards) for environments) - - -## Proposal - -This feature shall allow to specify how plugins can specify new types of package formats and environments to run test -commands in. - -Such plugins would take care of setting up the environment, create packages and run test commands using hooks provided -by tox. The actual knowledge how to create a certain package format is implement in the plugin. - -Plugin decides which is the required python interpreter to use in order to create the relevant package format. - - -```ini -[tox] -plugins=conda # virtualenv plugin is builtin; intention here is to bail out early in case the specified plugins - # are not installed -envlist=py27,py35 - -[testenv] -package_formats= # new option to specify wanted package formats for test environment using tox factors feature - # defaults to "sdist" if not set - py35: sdist wheel conda # names here are provided by plugins (reserved keywords) - py27: sdist conda -commands = py.test -``` - -Lising tox environments (`tox --list`) would display the following output: - -``` -(sdist) py27 -(conda) py27 -(sdist) py35 -(wheel) py35 -(conda) py35 -``` - -To remain backward-compatible, the package format will not be displayed if only a single package format is specified. - - - -How to skip building a package for a specific factor? - -Illustrate how to exclude a certain package format for a factor: - -```ini -[tox] -plugins=conda -envlist={py27,py35}, py27-xdist - -[testenv] -package_formats=sdist wheel conda -commands = py.test -exclude_package_formats= # new option which filters out packages - py27-xdist: wheel -``` - -Output of `tox --list`: - -``` -(sdist) py27 -(conda) py27 -(sdist) py35 -(wheel) py35 -(conda) py35 -(sdist) py27-xdist -(conda) py27-xdist -``` - - -### Implemenation Details - -``` -tox_package_formats() -> ['conda'] # ['sdist', 'wheel'] -tox_testenv_create(env_meta, package_type) -> # creates an environment for given package, using - # information from env_meta (like .envdir) - # returns: an "env" object which is forwaded to the next hooks -tox_testenv_install(env_meta, package_type, env) -> # installs deps and package into environment -tox_testenv_runtest(env_meta, package_type, env) -> # activates enviroment and runs test commands - -tox_testenv_updated(env_meta, package_type) -> # returns True if hte environment is already up to date - # otherwise, tox will remove the environment completely and - # create a new one -``` - - - diff --git a/doc/drafts/tox_conda_notes_niccodemus.md b/doc/drafts/tox_conda_notes_niccodemus.md deleted file mode 100644 index a54189a..0000000 --- a/doc/drafts/tox_conda_notes_niccodemus.md +++ /dev/null @@ -1,84 +0,0 @@ -[tox] -envlist=py27,py35 - -[testenv] -commands= py.test --timeout=180 {posargs:tests} -deps=pytest>=2.3.5 - pytest-timeout - -# USE CASE 1: plain conda, with deps on tox.ini -create_env_command = conda create --prefix {envdir} python={python_version} -install_command = conda install --prefix {envdir} {opts} {packages} -list_dependencies_command = conda list --prefix {envdir} - -# deprecated: see tox_create_popen hook -linux:env_activate_command=source activate {envdir} -win:env_activate_command=activate.bat {envdir} - -# USE CASE 2: plain conda, using requirements.txt -install_command = conda install --prefix {envdir} {opts} --file requirements.txt - -# USE CASE 3: conda env -create_env_command = conda env create --prefix {envdir} python={python_version} --file environment.yml -install_command = - -[testenv] -type=virtualenv -type=venv -type=conda -type=conda-reqs -type=conda-env - -1. Create a new ``create_env_command`` option. -;2. Create a new ``env_activate_command`` option (also consider how to make that platform dependent). -2. New substitution variable: {python_version} ('3.4', '2.7', etc') -3. env type concept: different types change the default options. - -1. tox_addoption can now add new "testenv" sections to tox.ini: - -[virtualenv] -[conda] -[venv] - -2. extend hooks: - - * tox_addoption - * tox_configure - for each requested env in config: - tox_testenv_up_to_date(envmeta) - tox_testenv_create(envmeta) - tox_testenv_install_deps(envmeta, env) - tox_runtest_pre(envmeta, env) - tox_runtest(envmeta, env, popen) - tox_runtest_post(envmeta, env) - -3. separate virtualenv details from "VirtualEnv" class into a plugin. - -[tox] -envlist={py27,py35}-{sdist,wheel,conda} - -[package-sdist] -command = python setup.py sdist - -[package-wheel] -command = python setup.py bdist_wheel - -[package-conda] -command = conda build ./conda-recipe - -[testenv:{sdist,wheel}] -commands = py.test - -[testenv:conda] -packages = sdist,wheel -commands = py.test --conda-only - -* tox_addoption -* tox_get_python_executable -* tox_configure -for each requested env in config: - tox_testenv_create(envmeta) - tox_testenv_install_deps(envmeta, env) - tox_runtest_pre(envmeta, env) - tox_runtest(envmeta, env, popen) - tox_runtest_post(envmeta, env) diff --git a/doc/example/basic.txt b/doc/example/basic.txt deleted file mode 100644 index 84fed34..0000000 --- a/doc/example/basic.txt +++ /dev/null @@ -1,313 +0,0 @@ -Basic usage -============================================= - -a simple tox.ini / default environments ------------------------------------------------ - -Put basic information about your project and the test environments you -want your project to run in into a ``tox.ini`` file that should -reside next to your ``setup.py`` file:: - - # content of: tox.ini , put in same dir as setup.py - [tox] - envlist = py26,py27 - [testenv] - deps=pytest # or 'nose' or ... - commands=py.test # or 'nosetests' or ... - -To sdist-package, install and test your project, you can -now type at the command prompt:: - - tox - -This will sdist-package your current project, create two virtualenv_ -Environments, install the sdist-package into the environments and run -the specified command in each of them. With:: - - tox -e py26 - -you can run restrict the test run to the python2.6 environment. - -Available "default" test environments names are:: - - py - py24 - py25 - py26 - py27 - py30 - py31 - py32 - py33 - py34 - jython - pypy - pypy3 - -The environment ``py`` uses the version of Python used to invoke tox. - -However, you can also create your own test environment names, -see some of the examples in :doc:`examples <../examples>`. - -specifying a platform ------------------------------------------------ - -.. versionadded:: 2.0 - -If you want to specify which platform(s) your test environment -runs on you can set a platform regular expression like this:: - - platform = linux2|darwin - -If the expression does not match against ``sys.platform`` -the test environment will be skipped. - -whitelisting non-virtualenv commands ------------------------------------------------ - -.. versionadded:: 1.5 - -Sometimes you may want to use tools not contained in your -virtualenv such as ``make``, ``bash`` or others. To avoid -warnings you can use the ``whitelist_externals`` testenv -configuration:: - - # content of tox.ini - [testenv] - whitelist_externals = make - /bin/bash - - -.. _virtualenv: http://pypi.python.org/pypi/virtualenv - -.. _multiindex: - -depending on requirements.txt ------------------------------------------------ - -.. versionadded:: 1.6.1 - -(experimental) If you have a ``requirements.txt`` file -you can add it to your ``deps`` variable like this:: - - deps = -rrequirements.txt - -All installation commands are executed using ``{toxinidir}`` -(the directory where ``tox.ini`` resides) as the current -working directory. Therefore, the underlying ``pip`` installation -will assume ``requirements.txt`` to exist at ``{toxinidir}/requirements.txt``. - -using a different default PyPI url ------------------------------------------------ - -.. versionadded:: 0.9 - -To install dependencies and packages from a different -default PyPI server you can type interactively:: - - tox -i http://pypi.testrun.org - -This causes tox to install dependencies and the sdist install step -to use the specificied url as the index server. - -You can cause the same effect by this ``tox.ini`` content:: - - [tox] - indexserver = - default = http://pypi.testrun.org - -installing dependencies from multiple PyPI servers ---------------------------------------------------- - -.. versionadded:: 0.9 - -You can instrument tox to install dependencies from -different PyPI servers, example:: - - [tox] - indexserver = - DEV = http://mypypiserver.org - - [testenv] - deps = - docutils # comes from standard PyPI - :DEV:mypackage # will be installed from custom "DEV" pypi url - -This configuration will install ``docutils`` from the default -Python PYPI server and will install the ``mypackage`` from -our ``DEV`` indexserver, and the respective ``http://mypypiserver.org`` -url. You can override config file settings from the command line -like this:: - - tox -i DEV=http://pypi.python.org/simple # changes :DEV: package URLs - tox -i http://pypi.python.org/simple # changes default - -further customizing installation ---------------------------------- - -.. versionadded:: 1.6 - -By default tox uses `pip`_ to install packages, both the -package-under-test and any dependencies you specify in ``tox.ini``. -You can fully customize tox's install-command through the -testenv-specific :confval:`install_command=ARGV` setting. -For instance, to use ``easy_install`` instead of `pip`_:: - - [testenv] - install_command = easy_install {opts} {packages} - -Or to use pip's ``--find-links`` and ``--no-index`` options to specify -an alternative source for your dependencies:: - - [testenv] - install_command = pip install --pre --find-links http://packages.example.com --no-index {opts} {packages} - -.. _pip: http://pip-installer.org - -forcing re-creation of virtual environments ------------------------------------------------ - -.. versionadded:: 0.9 - -To force tox to recreate a (particular) virtual environment:: - - tox --recreate -e py27 - -would trigger a complete reinstallation of the existing py27 environment -(or create it afresh if it doesn't exist). - -passing down environment variables -------------------------------------------- - -.. versionadded:: 2.0 - -By default tox will only pass the ``PATH`` environment variable (and on -windows ``SYSTEMROOT`` and ``PATHEXT``) from the tox invocation to the -test environments. If you want to pass down additional environment -variables you can use the ``passenv`` option:: - - [testenv] - passenv = LANG - -When your test commands execute they will execute with -the same LANG setting as the one with which tox was invoked. - -setting environment variables -------------------------------------------- - -.. versionadded:: 1.0 - -If you need to set an environment variable like ``PYTHONPATH`` you -can use the ``setenv`` directive:: - - [testenv] - setenv = - PYTHONPATH = {toxinidir}/subdir - -When your test commands execute they will execute with -a PYTHONPATH setting that will lead Python to also import -from the ``subdir`` below the directory where your ``tox.ini`` -file resides. - -special handling of PYTHONHASHSEED -------------------------------------------- - -.. versionadded:: 1.6.2 - -By default, Tox sets PYTHONHASHSEED_ for test commands to a random integer -generated when ``tox`` is invoked. This mimics Python's hash randomization -enabled by default starting `in Python 3.3`_. To aid in reproducing test -failures, Tox displays the value of ``PYTHONHASHSEED`` in the test output. - -You can tell Tox to use an explicit hash seed value via the ``--hashseed`` -command-line option to ``tox``. You can also override the hash seed value -per test environment in ``tox.ini`` as follows:: - - [testenv] - setenv = - PYTHONHASHSEED = 100 - -If you wish to disable this feature, you can pass the command line option -``--hashseed=noset`` when ``tox`` is invoked. You can also disable it from the -``tox.ini`` by setting ``PYTHONHASHSEED = 0`` as described above. - -.. _`in Python 3.3`: http://docs.python.org/3/whatsnew/3.3.html#builtin-functions-and-types -.. _PYTHONHASHSEED: http://docs.python.org/using/cmdline.html#envvar-PYTHONHASHSEED - -Integration with setuptools/distribute test commands ----------------------------------------------------- - -Distribute/Setuptools support test requirements -and you can extend its test command to trigger -a test run when ``python setup.py test`` is issued:: - - from setuptools.command.test import test as TestCommand - import sys - - class Tox(TestCommand): - user_options = [('tox-args=', 'a', "Arguments to pass to tox")] - def initialize_options(self): - TestCommand.initialize_options(self) - self.tox_args = None - def finalize_options(self): - TestCommand.finalize_options(self) - self.test_args = [] - self.test_suite = True - def run_tests(self): - #import here, cause outside the eggs aren't loaded - import tox - import shlex - args = self.tox_args - if args: - args = shlex.split(self.tox_args) - tox.cmdline(args=args) - - setup( - #..., - tests_require=['tox'], - cmdclass = {'test': Tox}, - ) - -Now if you run:: - - python setup.py test - -this will install tox and then run tox. You can pass arguments to ``tox`` -using the ``--tox-args`` or ``-a`` command-line options. For example:: - - python setup.py test -a "-epy27" - -is equivalent to running ``tox -epy27``. - -Ignoring a command exit code ----------------------------- - -In some cases, you may want to ignore a command exit code. For example:: - - [testenv:py27] - commands = coverage erase - {envbindir}/python setup.py develop - coverage run -p setup.py test - coverage combine - - coverage html - {envbindir}/flake8 loads - -By using the ``-`` prefix, similar to a ``make`` recipe line, you can ignore -the exit code for that command. - -Compressing dependency matrix ------------------------------ - -If you have a large matrix of dependencies, python versions and/or environments you can -use :ref:`generative-envlist` and :ref:`conditional settings <factors>` to express that in a concise form:: - - [tox] - envlist = py{26,27,33}-django{15,16}-{sqlite,mysql} - - [testenv] - deps = - django15: Django>=1.5,<1.6 - django16: Django>=1.6,<1.7 - 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 diff --git a/doc/example/devenv.txt b/doc/example/devenv.txt deleted file mode 100644 index f4afc37..0000000 --- a/doc/example/devenv.txt +++ /dev/null @@ -1,78 +0,0 @@ -======================= -Development environment -======================= - -Tox can be used for just preparing different virtual environments required by a -project. - -This feature can be used by deployment tools when preparing deployed project -environments. It can also be used for setting up normalized project development -environments and thus help reduce the risk of different team members using -mismatched development environments. - -Here are some examples illustrating how to set up a project's development -environment using tox. For illustration purposes, let us call the development -environment ``devenv``. - - -Example 1: Basic scenario -========================= - -Step 1 - Configure the development environment ----------------------------------------------- - -First, we prepare the tox configuration for our development environment by -defining a ``[testenv:devenv]`` section in the project's ``tox.ini`` -configuration file:: - - [testenv:devenv] - envdir = devenv - basepython = python2.7 - usedevelop = True - -In it we state: - -- what directory to locate the environment in, -- what Python executable to use in the environment, -- that our project should be installed into the environment using ``setup.py - develop``, as opposed to building and installing its source distribution using - ``setup.py install``. - -Actually, we can configure a lot more, and these are only the required settings. -For example, we can add the following to our configuration, telling tox not to -reuse ``commands`` or ``deps`` settings from the base ``[testenv]`` -configuration:: - - commands = - deps = - - -Step 2 - Create the development environment -------------------------------------------- - -Once the ``[testenv:devenv]`` configuration section has been defined, we create -the actual development environment by running the following:: - - tox -e devenv - -This creates the environment at the path specified by the environment's -``envdir`` configuration value. - - -Example 2: A more complex scenario -================================== - -Let us say we want our project development environment to: - -- be located in the ``devenv`` directory, -- use Python executable ``python2.7``, -- pull packages from ``requirements.txt``, located in the same directory as - ``tox.ini``. - -Here is an example configuration for the described scenario:: - - [testenv:devenv] - envdir = devenv - basepython = python2.7 - usedevelop = True - deps = -rrequirements.txt diff --git a/doc/example/general.txt b/doc/example/general.txt deleted file mode 100644 index 1a27549..0000000 --- a/doc/example/general.txt +++ /dev/null @@ -1,182 +0,0 @@ -.. be in -*- rst -*- mode! - -General tips and tricks -================================ - -Interactively passing positional arguments ------------------------------------------------ - -If you invoke ``tox`` like this:: - - tox -- -x tests/test_something.py - -the arguments after the ``--`` will be substituted -everywhere where you specify ``{posargs}`` in your -test commands, for example using ``py.test``:: - - # in the testenv or testenv:NAME section of your tox.ini - commands = - py.test {posargs} - -or using ``nosetests``:: - - commands = - nosetests {posargs} - -the above ``tox`` invocation will trigger the test runners to -stop after the first failure and to only run a particular test file. - -You can specify defaults for the positional arguments using this -syntax:: - - commands = - nosetests {posargs:--with-coverage} - -.. _`sphinx checks`: - -Integrating "sphinx" documentation checks ----------------------------------------------- - -In a ``testenv`` environment you can specify any command and -thus you can easily integrate sphinx_ documentation integrity during -a tox test run. Here is an example ``tox.ini`` configuration:: - - [testenv:docs] - basepython=python - changedir=doc - deps=sphinx - commands= - sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html - -This will create a dedicated ``docs`` virtual environment and install -the ``sphinx`` dependency which itself will install the ``sphinx-build`` tool -which you can then use as a test command. Note that sphinx output is redirected -to the virtualenv environment temporary directory to prevent sphinx -from caching results between runs. - -You can now call:: - - tox - -which will make the sphinx tests part of your test run. - - -.. _`TOXENV`: - -Selecting one or more environments to run tests against --------------------------------------------------------- - -Using the ``-e ENV[,ENV2,...]`` option you explicitely list -the environments where you want to run tests against. For -example, given the previous sphinx example you may call:: - - tox -e docs - -which will make ``tox`` only manage the ``docs`` environment -and call its test commands. You may specify more than -one environment like this:: - - tox -e py25,py26 - -which would run the commands of the ``py25`` and ``py26`` testenvironments -respectively. The special value ``ALL`` selects all environments. - -You can also specify an environment list in your ``tox.ini``:: - - [tox] - envlist = py25,py26 - -or override it from the command line or from the environment variable -``TOXENV``:: - - export TOXENV=py25,py26 # in bash style shells - -.. _artifacts: - -Access package artifacts between multiple tox-runs --------------------------------------------------------- - -If you have multiple projects using tox you can make use of -a ``distshare`` directory where ``tox`` will copy in sdist-packages so -that another tox run can find the "latest" dependency. This feature -allows to test a package against an unreleased development version -or even an uncommitted version on your own machine. - -By default, ``{homedir}/.tox/distshare`` will be used for -copying in and copying out artifacts (i.e. Python packages). - -For project ``two`` to depend on the ``one`` package you use -the following entry:: - - # example two/tox.ini - [testenv] - deps= - {distshare}/one-*.zip # install latest package from "one" project - -That's all. Tox running on project ``one`` will copy the sdist-package -into the ``distshare`` directory after which a ``tox`` run on project -``two`` will grab it because ``deps`` contain an entry with the -``one-*.zip`` pattern. If there is more than one matching package the -highest version will be taken. ``tox`` uses verlib_ to compare version -strings which must be compliant with :pep:`386`. - -If you want to use this with Jenkins_, also checkout the :ref:`jenkins artifact example`. - -.. _verlib: https://bitbucket.org/tarek/distutilsversion/ - -basepython defaults, overriding -++++++++++++++++++++++++++++++++++++++++++ - -By default, for any ``pyXY`` test environment name -the underlying "pythonX.Y" executable will be searched in -your system ``PATH``. It must exist in order to successfully create -virtualenv environments. On Windows a ``pythonX.Y`` named executable -will be searched in typical default locations using the -``C:\PythonX.Y\python.exe`` pattern. - -For ``jython`` and ``pypy`` the respective ``jython`` -and ``pypy-c`` names will be looked for. - -You can override any of the default settings by defining -the ``basepython`` variable in a specific test environment -section, for example:: - - [testenv:py27] - basepython=/my/path/to/python2.7 - -Avoiding expensive sdist ------------------------- - -Some projects are large enough that running an sdist, followed by -an install every time can be prohibitively costly. To solve this, -there are two different options you can add to the ``tox`` section. First, -you can simply ask tox to please not make an sdist:: - - [tox] - skipsdist=True - -If you do this, your local software package will not be installed into -the virtualenv. You should probably be okay with that, or take steps -to deal with it in your commands section:: - - [testenv] - commands = - python setup.py develop - py.test - -Running ``setup.py develop`` is a common enough model that it has its own -option:: - - [testenv] - usedevelop=True - -And a corresponding command line option ``--develop``, which will set -``skipsdist`` to True and then perform the ``setup.py develop`` -step at the place where ``tox`` normally perfoms the installation of the sdist. -Specifically, it actually runs ``pip install -e .`` behind the scenes, which -itself calls ``setup.py develop``. - -There is an optimization coded in to not bother re-running the command if -``$projectname.egg-info`` is newer than ``setup.py`` or ``setup.cfg``. - -.. include:: ../links.txt diff --git a/doc/example/jenkins.txt b/doc/example/jenkins.txt deleted file mode 100644 index 94cb22d..0000000 --- a/doc/example/jenkins.txt +++ /dev/null @@ -1,174 +0,0 @@ - -Using Tox with the Jenkins Integration Server -================================================= - -Using Jenkins multi-configuration jobs -------------------------------------------- - -The Jenkins_ continuous integration server allows to define "jobs" with -"build steps" which can be test invocations. If you :doc:`install <../install>` ``tox`` on your -default Python installation on each Jenkins slave, you can easily create -a Jenkins multi-configuration job that will drive your tox runs from the CI-server side, -using these steps: - -* install the Python plugin for Jenkins under "manage jenkins" -* create a "multi-configuration" job, give it a name of your choice -* configure your repository so that Jenkins can pull it -* (optional) configure multiple nodes so that tox-runs are performed - on multiple hosts -* configure ``axes`` by using :ref:`TOXENV <TOXENV>` as an axis - name and as values provide space-separated test environment names - you want Jenkins/tox to execute. - -* add a **Python-build step** with this content (see also next example):: - - import tox - tox.cmdline() # environment is selected by ``TOXENV`` env variable - -* check ``Publish JUnit test result report`` and enter - ``**/junit-*.xml`` as the pattern so that Jenkins collects - test results in the JUnit XML format. - -The last point requires that your test command creates JunitXML files, -for example with ``py.test`` it is done like this: - -.. code-block:: ini - - commands = py.test --junitxml=junit-{envname}.xml - - - -**zero-installation** for slaves -------------------------------------------------------------- - -.. note:: - - This feature is broken currently because "toxbootstrap.py" - has been removed. Please file an issue if you'd like to - see it back. - -If you manage many Jenkins slaves and want to use the latest officially -released tox (or latest development version) and want to skip manually -installing ``tox`` then substitute the above **Python build step** code -with this:: - - import urllib, os - url = "https://bitbucket.org/hpk42/tox/raw/default/toxbootstrap.py" - #os.environ['USETOXDEV']="1" # use tox dev version - d = dict(__file__='toxbootstrap.py') - exec urllib.urlopen(url).read() in d - d['cmdline'](['--recreate']) - -The downloaded `toxbootstrap.py` file downloads all neccessary files to -install ``tox`` in a virtual sub environment. Notes: - -* uncomment the line containing ``USETOXDEV`` to use the latest - development-release version of tox instead of the - latest released version. - -* adapt the options in the last line as needed (the example code - will cause tox to reinstall all virtual environments all the time - which is often what one wants in CI server contexts) - - -Integrating "sphinx" documentation checks in a Jenkins job ----------------------------------------------------------------- - -If you are using a multi-configuration Jenkins job which collects -JUnit Test results you will run into problems using the previous -method of running the sphinx-build command because it will not -generate JUnit results. To accomodate this issue one solution -is to have ``py.test`` wrap the sphinx-checks and create a -JUnit result file which wraps the result of calling sphinx-build. -Here is an example: - -1. create a ``docs`` environment in your ``tox.ini`` file like this:: - - [testenv:docs] - basepython=python - changedir=doc # or whereever you keep your sphinx-docs - deps=sphinx - py - commands= - py.test --tb=line -v --junitxml=junit-{envname}.xml check_sphinx.py - -2. create a ``doc/check_sphinx.py`` file like this:: - - import py - import subprocess - def test_linkcheck(tmpdir): - doctrees = tmpdir.join("doctrees") - htmldir = tmpdir.join("html") - subprocess.check_call( - ["sphinx-build", "-W", "-blinkcheck", - "-d", str(doctrees), ".", str(htmldir)]) - def test_build_docs(tmpdir): - doctrees = tmpdir.join("doctrees") - htmldir = tmpdir.join("html") - subprocess.check_call([ - "sphinx-build", "-W", "-bhtml", - "-d", str(doctrees), ".", str(htmldir)]) - -3. run ``tox -e docs`` and then you may integrate this environment - along with your other environments into Jenkins. - -Note that ``py.test`` is only installed into the docs environment -and does not need to be in use or installed with any other environment. - -.. _`jenkins artifact example`: - -Access package artifacts between Jenkins jobs --------------------------------------------------------- - -.. _`Jenkins Copy Artifact plugin`: http://wiki.jenkins-ci.org/display/HUDSON/Copy+Artifact+Plugin - -In an extension to :ref:`artifacts` you can also configure Jenkins jobs to -access each others artifacts. ``tox`` uses the ``distshare`` directory -to access artifacts and in a Jenkins context (detected via existence -of the environment variable ``HUDSON_URL``); it defaults to -to ``{toxworkdir}/distshare``. - -This means that each workspace will have its own ``distshare`` -directory and we need to configure Jenkins to perform artifact copying. -The recommend way to do this is to install the `Jenkins Copy Artifact plugin`_ -and for each job which "receives" artifacts you add a **Copy artifacts from another project** build step using roughly this configuration:: - - Project-name: name of the other (tox-managed) job you want the artifact from - Artifacts to copy: .tox/dist/*.zip # where tox jobs create artifacts - Target directory: .tox/distshare # where we want it to appear for us - Flatten Directories: CHECK # create no subdir-structure - -You also need to configure the "other" job to archive artifacts; This -is done by checking ``Archive the artifacts`` and entering:: - - Files to archive: .tox/dist/*.zip - -So our "other" job will create an sdist-package artifact and -the "copy-artifacts" plugin will copy it to our ``distshare`` area. -Now everything proceeds as :ref:`artifacts` shows it. - -So if you are using defaults you can re-use and debug exactly the -same ``tox.ini`` file and make use of automatic sharing of -your artifacts between runs or Jenkins jobs. - - -Avoiding the "path too long" error with long shebang lines ---------------------------------------------------------------- - -If you are using Jenkins builds you might run into the issue -that tox can not call ``pip`` because the so called "shebang" -line is too long. There is a limit of 127 chars on some systems. -Probably the best way to fix the problem is to use the -new ``--workdir`` option which tells tox to use a specific -directory for its virtualenvironments. Set it to some unique -enough short path. If somebody is interested to do a PR -you could add a new option to tox which uses a random -directory for storing its workdir results and removes -it after the tox run finishes. This could be used -from CI environments where you probably anyway want -to recreate everything on new runs. - - -.. include:: ../links.txt - - diff --git a/doc/example/nose.txt b/doc/example/nose.txt deleted file mode 100644 index ec97f18..0000000 --- a/doc/example/nose.txt +++ /dev/null @@ -1,41 +0,0 @@ - -nose and tox -================================= - -It is easy to integrate `nosetests`_ runs with tox. -For starters here is a simple ``tox.ini`` config to configure your project -for running with nose: - -Basic nosetests example --------------------------- - -Assuming the following layout:: - - tox.ini # see below for content - setup.py # a classic distutils/setuptools setup.py file - -and the following ``tox.ini`` content:: - - [testenv] - deps=nose - commands= - nosetests \ - [] # substitute with tox' positional arguments - -you can invoke ``tox`` in the directory where your ``tox.ini`` resides. -``tox`` will sdist-package your project create two virtualenv environments -with the ``python2.6`` and ``python2.5`` interpreters, respectively, and will -then run the specified test command. - - -More examples? ------------------------------------------- - -You can use and combine other features of ``tox`` with your tox runs, -e.g. :ref:`sphinx checks`. If you figure out some particular configurations -for nose/tox interactions please submit them. - -Also you might want to checkout :doc:`general`. - -.. include:: ../links.txt - diff --git a/doc/example/pytest.txt b/doc/example/pytest.txt deleted file mode 100755 index 6f98cf3..0000000 --- a/doc/example/pytest.txt +++ /dev/null @@ -1,111 +0,0 @@ - -py.test and tox -================================= - -It is easy to integrate `py.test`_ runs with tox. If you encounter -issues, please check if they are `listed as a known issue`_ and/or use -the :doc:`support channels <../support>`. - -Basic example --------------------------- - -Assuming the following layout:: - - tox.ini # see below for content - setup.py # a classic distutils/setuptools setup.py file - -and the following ``tox.ini`` content:: - - [tox] - envlist = py26,py31 - - [testenv] - deps=pytest # PYPI package providing py.test - commands= - py.test \ - {posargs} # substitute with tox' positional arguments - -you can now invoke ``tox`` in the directory where your ``tox.ini`` resides. -``tox`` will sdist-package your project, create two virtualenv environments -with the ``python2.6`` and ``python3.1`` interpreters, respectively, and will -then run the specified test command in each of them. - -Extended example: change dir before test and use per-virtualenv tempdir --------------------------------------------------------------------------- - -Assuming the following layout:: - - tox.ini # see below for content - setup.py # a classic distutils/setuptools setup.py file - tests # the directory containing tests - -and the following ``tox.ini`` content:: - - [tox] - envlist = py26,py31 - [testenv] - changedir=tests - deps=pytest - commands= - py.test \ - --basetemp={envtmpdir} \ # py.test tempdir setting - {posargs} # substitute with tox' positional arguments - -you can invoke ``tox`` in the directory where your ``tox.ini`` resides. -Differently than in the previous example the ``py.test`` command -will be executed with a current working directory set to ``tests`` -and the test run will use the per-virtualenv temporary directory. - -.. _`passing positional arguments`: - -Using multiple CPUs for test runs ------------------------------------ - -``py.test`` supports distributing tests to multiple processes and hosts -through the `pytest-xdist`_ plugin. Here is an example configuration -to make ``tox`` use this feature:: - - [testenv] - deps=pytest-xdist - changedir=tests - commands= - py.test \ - --basetemp={envtmpdir} \ - --confcutdir=.. \ - -n 3 \ # use three sub processes - {posargs} - -.. _`listed as a known issue`: - -Known Issues and limitations ------------------------------ - -**Too long filenames**. you may encounter "too long filenames" for temporarily -created files in your py.test run. Try to not use the "--basetemp" parameter. - -**installed-versus-checkout version**. ``py.test`` collects test -modules on the filesystem and then tries to import them under their -`fully qualified name`_. This means that if your test files are -importable from somewhere then your ``py.test`` invocation may end up -importing the package from the checkout directory rather than the -installed package. - -There are a few ways to prevent this. - -With installed tests (the tests packages are known to ``setup.py``), a -safe and explicit option is to give the explicit path -``{envsitepackagesdir}/mypkg`` to pytest. -Alternatively, it is possible to use ``changedir`` so that checked-out -files are outside the import path, then pass ``--pyargs mypkg`` to -pytest. - -With tests that won't be installed, the simplest way to run them -against your installed package is to avoid ``__init__.py`` files in test -directories; pytest will still find and import them by adding their -parent directory to ``sys.path`` but they won't be copied to -other places or be found by Python's import system outside of pytest. - -.. _`fully qualified name`: http://pytest.org/latest/goodpractises.html#test-package-name - - -.. include:: ../links.txt diff --git a/doc/example/result.txt b/doc/example/result.txt deleted file mode 100644 index b3b95b4..0000000 --- a/doc/example/result.txt +++ /dev/null @@ -1,44 +0,0 @@ - -Writing a json result file --------------------------------------------------------- - -.. versionadded: 1.6 - -You can instruct tox to write a json-report file via:: - - tox --result-json=PATH - -This will create a json-formatted result file using this schema:: - - { - "testenvs": { - "py27": { - "python": { - "executable": "/home/hpk/p/tox/.tox/py27/bin/python", - "version": "2.7.3 (default, Aug 1 2012, 05:14:39) \n[GCC 4.6.3]", - "version_info": [ 2, 7, 3, "final", 0 ] - }, - "test": [ - { - "output": "...", - "command": [ - "/home/hpk/p/tox/.tox/py27/bin/py.test", - "--instafail", - "--junitxml=/home/hpk/p/tox/.tox/py27/log/junit-py27.xml", - "tests/test_config.py" - ], - "retcode": "0" - } - ], - "setup": [] - } - }, - "platform": "linux2", - "installpkg": { - "basename": "tox-1.6.0.dev1.zip", - "sha256": "b6982dde5789a167c4c35af0d34ef72176d0575955f5331ad04aee9f23af4326", - "md5": "27ead99fd7fa39ee7614cede6bf175a6" - }, - "toxversion": "1.6.0.dev1", - "reportversion": "1" - } diff --git a/doc/example/unittest.txt b/doc/example/unittest.txt deleted file mode 100644 index 5dcaa8e..0000000 --- a/doc/example/unittest.txt +++ /dev/null @@ -1,89 +0,0 @@ - -unittest2, discover and tox -=============================== - -Running unittests with 'discover' ------------------------------------------- - -.. _Pygments: http://pypi.python.org/pypi/Pygments - -The discover_ project allows to discover and run unittests -and we can easily integrate it in a ``tox`` run. As an example, -perform a checkout of Pygments_:: - - hg clone https://bitbucket.org/birkenfeld/pygments-main - -and add the following ``tox.ini`` to it:: - - [tox] - envlist = py25,py26,py27 - - [testenv] - changedir=tests - commands=discover - deps=discover - -If you now invoke ``tox`` you will see the creation of -three virtual environments and a unittest-run performed -in each of them. - -Running unittest2 and sphinx tests in one go ------------------------------------------------------ - -.. _`Michael Foord`: http://www.voidspace.org.uk/ -.. _tox.ini: http://code.google.com/p/mock/source/browse/tox.ini - -`Michael Foord`_ has contributed a ``tox.ini`` file that -allows you to run all tests for his mock_ project, -including some sphinx-based doctests. If you checkout -its repository with: - - hg clone https://code.google.com/p/mock/ - -the checkout has a tox.ini_ that looks like this:: - - [tox] - envlist = py24,py25,py26,py27 - - [testenv] - deps=unittest2 - commands=unit2 discover [] - - [testenv:py26] - commands= - unit2 discover [] - sphinx-build -b doctest docs html - sphinx-build docs html - deps = - unittest2 - sphinx - - [testenv:py27] - commands= - unit2 discover [] - sphinx-build -b doctest docs html - sphinx-build docs html - deps = - unittest2 - sphinx - -mock uses unittest2_ to run the tests. Invoking ``tox`` starts test -discovery by executing the ``unit2 discover`` -commands on Python 2.4, 2.5, 2.6 and 2.7 respectively. Against -Python2.6 and Python2.7 it will additionally run sphinx-mediated -doctests. If building the docs fails, due to a reST error, or -any of the doctests fails, it will be reported by the tox run. - -The ``[]`` parentheses in the commands provide :ref:`positional substitution` which means -you can e.g. type:: - - tox -- -f -s SOMEPATH - -which will ultimately invoke:: - - unit2 discover -f -s SOMEPATH - -in each of the environments. This allows you to customize test discovery -in your ``tox`` runs. - -.. include:: ../links.txt diff --git a/doc/examples.txt b/doc/examples.txt deleted file mode 100644 index a3e9d91..0000000 --- a/doc/examples.txt +++ /dev/null @@ -1,15 +0,0 @@ - -tox configuration and usage examples -============================================================================== - -.. toctree:: - :maxdepth: 2 - - example/basic.txt - example/pytest.txt - example/unittest - example/nose.txt - example/general.txt - example/jenkins.txt - example/devenv.txt - diff --git a/doc/index.txt b/doc/index.txt deleted file mode 100644 index e1bc20e..0000000 --- a/doc/index.txt +++ /dev/null @@ -1,123 +0,0 @@ -Welcome to the tox automation project -=============================================== - -vision: standardize testing in Python ---------------------------------------------- - -``tox`` aims to automate and standardize testing in Python. It is part -of a larger vision of easing the packaging, testing and release process -of Python software. - -What is Tox? --------------------- - -Tox is a generic virtualenv_ management and test command line tool you can use for: - -* checking your package installs correctly with different Python versions and - interpreters - -* running your tests in each of the environments, configuring your test tool of choice - -* acting as a frontend to Continuous Integration servers, greatly - reducing boilerplate and merging CI and shell-based testing. - - -Basic example ------------------ - -First, install ``tox`` with ``pip install tox`` or ``easy_install tox``. -Then put basic information about your project and the test environments you -want your project to run in into a ``tox.ini`` file residing -right next to your ``setup.py`` file:: - - # content of: tox.ini , put in same dir as setup.py - [tox] - envlist = py26,py27 - [testenv] - deps=pytest # install pytest in the venvs - commands=py.test # or 'nosetests' or ... - -You can also try generating a ``tox.ini`` file automatically, by running -``tox-quickstart`` and then answering a few simple questions. - -To sdist-package, install and test your project against Python2.6 and Python2.7, just type:: - - tox - -and watch things happening (you must have python2.6 and python2.7 installed in your -environment otherwise you will see errors). When you run ``tox`` a second time -you'll note that it runs much faster because it keeps track of virtualenv details -and will not recreate or re-install dependencies. You also might want to -checkout :doc:`examples` to get some more ideas. - -Current features -------------------- - -* **automation of tedious Python related test activities** - -* **test your Python package against many interpreter and dependency configs** - - - automatic customizable (re)creation of virtualenv_ test environments - - - installs your ``setup.py`` based project into each virtual environment - - - test-tool agnostic: runs py.test, nose or unittests in a uniform manner - -* :doc:`(new in 2.0) plugin system <plugins>` to modify tox execution with simple hooks. - -* uses pip_ and setuptools_ by default. Support for configuring the installer command - through :confval:`install_command=ARGV`. - -* **cross-Python compatible**: CPython-2.6, 2.7, 3.2 and higher, - Jython and pypy_. - -* **cross-platform**: Windows and Unix style environments - -* **integrates with continuous integration servers** like Jenkins_ - (formerly known as Hudson) and helps you to avoid boilerplatish - and platform-specific build-step hacks. - -* **full interoperability with devpi**: is integrated with and - is used for testing in the devpi_ system, a versatile pypi - index server and release managing tool. - -* **driven by a simple ini-style config file** - -* **documented** :doc:`examples <examples>` and :doc:`configuration <config>` - -* **concise reporting** about tool invocations and configuration errors - -* **professionally** :doc:`supported <support>` - -* supports :ref:`using different / multiple PyPI index servers <multiindex>` - - -.. _pypy: http://pypy.org - -.. _`tox.ini`: :doc:configfile - -.. toctree:: - :hidden: - - install - examples - config - config-v2 - support - changelog - links - plugins - example/result - announce/release-0.5 - announce/release-1.0 - announce/release-1.1 - announce/release-1.2 - announce/release-1.3 - announce/release-1.4 - announce/release-1.4.3 - announce/release-1.8 - announce/release-1.9 - announce/release-2.0 - - -.. include:: links.txt diff --git a/doc/install.txt b/doc/install.txt deleted file mode 100644 index 982cefb..0000000 --- a/doc/install.txt +++ /dev/null @@ -1,44 +0,0 @@ -tox installation -================================== - -Install info in a nutshell ----------------------------------- - -**Pythons**: CPython 2.6-3.5, Jython-2.5.1, pypy-1.9ff - -**Operating systems**: Linux, Windows, OSX, Unix - -**Installer Requirements**: setuptools_ - -**License**: MIT license - -**hg repository**: https://bitbucket.org/hpk42/tox - -Installation with pip/easy_install --------------------------------------- - -Use one of the following commands:: - - pip install tox - easy_install tox - -It is fine to install ``tox`` itself into a virtualenv_ environment. - -Install from Checkout -------------------------- - -Consult the Bitbucket page to get a checkout of the mercurial repository: - - https://bitbucket.org/hpk42/tox - -and then install in your environment with something like:: - - python setup.py install - -or just activate your checkout in your environment like this:: - - python setup.py develop - -so that you can do changes and submit patches. - -.. include:: links.txt diff --git a/doc/links.txt b/doc/links.txt deleted file mode 100644 index 9c16034..0000000 --- a/doc/links.txt +++ /dev/null @@ -1,20 +0,0 @@ - -.. _devpi: http://doc.devpi.net -.. _Python: http://www.python.org -.. _virtualenv: https://pypi.python.org/pypi/virtualenv -.. _virtualenv3: https://pypi.python.org/pypi/virtualenv3 -.. _virtualenv5: https://pypi.python.org/pypi/virtualenv5 -.. _`py.test`: http://pytest.org -.. _nosetests: -.. _`nose`: https://pypi.python.org/pypi/nose -.. _`Holger Krekel`: https://twitter.com/hpk42 -.. _`pytest-xdist`: https://pypi.python.org/pypi/pytest-xdist - -.. _`easy_install`: http://peak.telecommunity.com/DevCenter/EasyInstall -.. _pip: https://pypi.python.org/pypi/pip -.. _setuptools: https://pypi.python.org/pypi/setuptools -.. _`jenkins`: http://jenkins-ci.org/ -.. _sphinx: https://pypi.python.org/pypi/Sphinx -.. _discover: https://pypi.python.org/pypi/discover -.. _unittest2: https://pypi.python.org/pypi/unittest2 -.. _mock: https://pypi.python.org/pypi/mock/ diff --git a/doc/plugins.txt b/doc/plugins.txt deleted file mode 100644 index be3665a..0000000 --- a/doc/plugins.txt +++ /dev/null @@ -1,88 +0,0 @@ -.. be in -*- rst -*- mode! - -tox plugins -=========== - -.. versionadded:: 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 ---------------------------------------- - -.. automodule:: tox.hookspecs - :members: - -.. autoclass:: tox.config.Parser() - :members: - -.. autoclass:: tox.config.Config() - :members: - -.. autoclass:: tox.config.TestenvConfig() - :members: - -.. autoclass:: tox.venv.VirtualEnv() - :members: - -.. autoclass:: tox.session.Session() - :members: diff --git a/doc/support.txt b/doc/support.txt deleted file mode 100644 index 29962e7..0000000 --- a/doc/support.txt +++ /dev/null @@ -1,36 +0,0 @@ - -.. _support: - -support and contact channels -===================================== - -Getting in contact: - -* join the `Testing In Python (TIP) mailing list`_ for general and tox/test-tool - interaction questions. -* file a `report on the issue tracker`_ -* hang out on the irc.freenode.net #pylib channel -* `clone the mercurial repository`_ and submit patches -* the `tetamap blog`_, `holger's twitter presence`_ or - for private inquiries holger krekel at gmail. - -professional support ----------------------------- - -.. note:: Upcoming: `professional testing with pytest and tox <`http://www.python-academy.com/courses/specialtopics/python_course_testing.html>`_ , 24th-26th June 2013, Leipzig. - -If you are looking for on-site teaching or consulting support, -contact holger at `merlinux.eu`_, an association of -experienced well-known Python developers. - -.. _`Maciej Fijalkowski`: http://www.ohloh.net/accounts/fijal -.. _`Benjamin Peterson`: http://www.ohloh.net/accounts/gutworth -.. _`Testing In Python (TIP) mailing list`: http://lists.idyll.org/listinfo/testing-in-python -.. _`holger's twitter presence`: http://twitter.com/hpk42 -.. _`merlinux.eu`: http://merlinux.eu -.. _`report on the issue tracker`: https://bitbucket.org/hpk42/tox/issues?status=new&status=open -.. _`tetamap blog`: http://holgerkrekel.net -.. _`tox-dev`: http://codespeak.net/mailman/listinfo/tox-dev -.. _`tox-commit`: http://codespeak.net/mailman/listinfo/tox-commit -.. _`clone the mercurial repository`: https://bitbucket.org/hpk42/tox - |