2. Developer Environment

Developers are free to setup whatever environment that they may need to facilitate their work. However, each of the Python packages in the repository includes a tox setup, which developers can also use to automatically setup and manage dedicated venvs for different predefined development tasks.

2.1. Development with tox

The following is a rough guide to help install tox as a command line tool in a dedicated, minimal virtual environment and is based on a webinar by Oliver Bestwalter. His solution is nice since tox is made available with no need to manually activate its virtual environment.

Note

Developers that would like to use tox should, at the very least, learn enough about it that they understand the difference between running tox and tox -r.

To create a Python virtual environment that solely hosts tox, execute some variation of the following using the desired target Python

$ cd $HOME/local/venv
$ deactivate (to deactivate the current virtual environment if you are in one)
$ /path/to/desired/python --version
$ /path/to/desired/python -m venv $HOME/local/venv/.toxbase
$ ./.toxbase/bin/python -m pip list
$ ./.toxbase/bin/python -m pip install --upgrade pip setuptools (if installed)
$ ./.toxbase/bin/python -m pip install tox
$ ./.toxbase/bin/python -m pip list
$ ./.toxbase/bin/tox --version

To avoid having to activate .toxbase every time we would like to work with tox, we setup tox in PATH. Note that developers can use this single tox installation for multiple projects. Please replace .bash_profile with the appropriate shell configuration file and tailor the following to your needs.

$ mkdir $HOME/local/bin
$ ln -s $HOME/local/venv/.toxbase/bin/tox $HOME/local/bin/tox
$ vi $HOME/.bash_profile (add $HOME/local/bin to PATH)
$ . $HOME/.bash_profile
$ which tox
$ tox --version

No work will be carried out by default with the calls tox and tox -r.

The following tasks can be run from within the directory hierarchy that contains the package’s tox configuration file

/path/to/bfrescox_pypkg/tox.ini

  • tox -r -e coverage

    • Execute the full test suite for the package and save coverage results to the coverage file

    • The test runs the package code in the local clone rather than code installed into Python so that coverage results accessed through web services such as CodeCov are clean and straightforward

    • If the environment variable COVERAGE_FILE is set, then this is the coverage file that will be written to. If it is not specified, then the coverage results are written to .coverage_bfrescox for Bfrescox or .coverage_bfrescoxpro for Bfrescoxpro.

  • tox -r -e nocoverage

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

  • tox -r -e report

    • It is intended that this 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

    • For both packages, the environment variables COVERAGE_XML and COVERAGE_HTML can be provided to specify the names of the files that the associated reports should be written to. If COVERAGE_XML is not specified, then the XML report is written to coverage.xml. If COVERAGE_HTML is not provided, then the HTML report is written to htmlcov.

  • tox -r -e check

    • Run several checks on the code to report possible issues

    • No files are altered automatically by this task

  • tox -r -e html (Bfrescox only)

    • Generate and render documentation locally in HTML

  • tox -r -e pdf (Bfrescox only)

    • Generate and render the documentation locally as a PDF file

    • Users are responsible for installing make and a compatible LaTeX installation for immediate use by tox.

  • tox -e book (Bfrescox only)

    • Generate from scratch in book/_build the Bfrescox examples Jupyter book

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

2.2. Direct use of tox venvs

Many of the tox tasks will build their Bfrescox or Bfrescoxpro binary automatically each time they are run, which can significantly slow development work. In such cases, a developer will likely start their work by creating a clean virtual environment for their task using tox -r and subsequently load and work in that venv directly.

Developer’s can inspect tox.ini to see what commands are run by their task and adapt these for their work.

The following example shows how to run only a single test case using the coverage virtual environment setup by tox.

$ cd /path/to/bfrescox_pypkg
$ tox -r -e coverage
$ . ./.tox/coverage/bin/activate
$ which python
$ python --version
$ python -m pip list
$ python -m unittest bfrescox.tests.TestConfiguration

Note that using the coverage venv directly can be particularly useful since the package is installed in editable mode and therefore facilitates interactive development and testing of the Python code.