2. Developer Environment

The POptUS repository contains a tox setup that defines different predefined development tasks, each of which is run in a dedicated Python virtual environment created and managed automatically by tox.

2.1. Development with tox

Developers must first install tox and make it available as a command line tool in order to run tasks. To follow suggestions by Oliver Bestwalter, install tox in a dedicated virtual environment and add it to PATH by adapting the following to your setup

$ /path/to/desired/python -m venv ~/local/venv/.toxbase
$ ~/local/venv/.toxbase/bin/python -m pip install tox
$ ln -s ~/local/venv/.toxbase/bin/tox ~/local/bin/tox

(add ~/local/bin to PATH in shell's configuration file and source)

$ which tox
$ tox --version

No default tasks are executed by the calls tox and tox -r. The following tasks can be run from within the /path/to/POptUS/poptus_pypkg folder hierarchy

  • tox -e coverage

    • Execute the full test suite for the package and save coverage results to the coverage file. The task runs the the test on code in the developer’s clone (pip install’s editable mode).

    • The COVERAGE_FILE environment variable can optionally be set to define the name of the file that coverage results will be written to. By default, results are written to .coverage_poptus.

  • tox -e nocoverage

    • Execute the full test suite for the package using the code installed into Python.

  • tox -e report

    • This task should be run after or with coverage

    • Display a code coverage report for the package’s full test suite and generate XML and HTML versions of the report.

    • The COVERAGE_XML and COVERAGE_HTML environment variables can optionally be set to define the name of the XML- and HTML-format reports. Default report names are coverage.xml and htmlcov.

  • tox -e check

    • Report issues if code does not adhere to project-specific standards.

  • tox -e html

    • Generate and render documentation in HTML format

  • tox -e pdf

    • Generate and render documentation as a PDF file

    • This task uses make and requires a LaTeX installation.

Additionally, you can run any combination of the above such as tox -e report,coverage.

Note that each task can be run as tox -r -e <task> or tox -e <task>. Developers are responsible for determining which is correct for their current situation.

2.2. Direct use of tox venvs

The virtual environments created automatically by tox can be used directly by developers. Using the coverage environment, for example, can be useful since its editable mode installation can facilitate interactive development and testing of the Python code. To run a single test case directly using the coverage environment, for example, execute

$ cd /path/to/poptus_pypkg
$ tox -r -e coverage
$ . ./.tox/coverage/bin/activate
$ python -m unittest poptus.tests.TestTemplate