Python task automation tool tox tutorial

Command line driven CI frontend and development task automation tool

tox github

Its core role is to support the creation of isolated Python environments where different versions of Python interpreters and various dependency libraries can be installed to facilitate automated testing, packaging, continuous integration, and other things.

In short, tox is a command-line tool for managing test virtual environments. It has been around for years and is widely used by developers, for example, the famous cloud computing platform OpenStack has adopted it as one of the most basic testing tools.

1.What can tox do?

The breakdown of uses includes：

• Create development environment

• Run static code analysis and testing tools

• Automated build packages

• Run tests against tox-built packages

• Check that the package installs smoothly with different Python versions/interpreters

• Unified Continuous Integration (CI) and Command Line Based Testing

• Create and deploy project documentation

• Distribute the package to PyPI or any other platform

The official tox documentation lists more than 40 example usage scenarios, a detailed list of which can be found in：https://tox.readthedocs.io/en/latest/examples.html

2.tox How is it configured?

About its usage: use pip install tox to install, tox to run the full test environment, and tox -e envname to run the specified environment. There are also quite a few command line arguments, which are viewed via tox -h.

The behavior of tox is controlled by its configuration file, which currently supports 3 types of configuration files：

1. pyproject.toml

2. tox.ini

3. setup.cfg

Taking the tox project's own tox.ini configuration as an example, you can see that it is configured like this（https://github.com/tox-dev/tox/blob/master/tox.ini）：

Each [xxx] and the contents below it form a section, with blank lines separating each section.

Below [tox] are global configuration items, and the envlist field defines the environment in which tox will operate. Under [xxx] are the configuration items for the xxx virtual environment. [xxx:yyy] inherits the xxx configuration and gives higher priority to its own configuration items.

For each virtual environment, there are many configuration items available, such as description, basepython, deps, commands, and so on.

tox also supports variable substitution, and it provides some built-in base variables (global or for virtual environments): {toxinidir}, {homedir}, {envname}, {envdir}, etc.

In addition to basic variable substitution, it supports these advanced uses：

• Takes the operating system environment variable: {env:KEY}, which is equivalent to os.environ['KEY']. This can be changed to: {env:KEY:DEFAULTVALUE}, which uses the default value if the environment variable is not fetched; {env:KEY:{env:DEFAULT_OF_KEY}}, which achieves an if-else fetching effect

• Pass command line arguments: {posargs:DEFAULTS}, use DEFAULTS value when there is no command line argument. Usage: tox arg1 arg2 pass two arguments, or tox -- --opt1 arg1 pass "--opt1 arg1" as a whole.

• Passing values between sections: {[sectionname]valuename}, content from different sections can be passed for use.

  Interactive console injection: {tty:ON_VALUE:OFF_VALUE}, the first value is used when the interactive shell console is on, otherwise the second one is used. pytest is an example of this when using "--pdb".

The brackets "{}" can be used not only as a variable substitution, but also as a value for the "or relation" judgment. Look directly at the following example：

[tox]
envlist = {py27,py36}-django{15,16}

The 2 sets of brackets in {py27,py36}-django{15,16} have 2 values each, and they can actually be combined into 4 environments: py27-django15, py27-django16, py36-django15, py36-django16.

For more information on what configuration items are available for tox, conditions of use, what they mean, advanced usage, etc., see the official documentation at

：https://tox.readthedocs.io/en/latest/config.html

3.Plugging in tox

In addition to its powerful configurability, tox is also highly extensible, it is pluggable, and an extremely rich plugin ecosystem has been created around it.

Using pip search tox, you can see a large number of libraries starting with "tox-", which are all tox plug-in packages. There are many familiar names such as setuptools, pipenv, conda, travis, pytest, docker, and so on.

tox opens up a lot of API interfaces for others to develop custom plugins.

4.The workflow of tox

Next, see how tox works：

The main links in its workflow are：

• Configuration: load configuration files (such as tox.ini), parse command line parameters, read system environment variables, etc.

• Packaging: optional, for projects with setup.py files, you can generate its source distribution in this step

• Create a virtual environment: use virtualenv by default to create a virtual environment and install the required dependencies according to the "deps" in the configuration, then execute the configured commands (commands)

• report：Summarize the results of all virtual environments and list them

5.Summary

tox itself is a testing tool that tries to automate, standardize, and streamline Pytho testing. But unlike unittest and pytest, which are testing frameworks, it works beyond the code level and is a project-level tool. Therefore, it needs to be combined with these testing frameworks or handle multiple automation tasks (e.g. running pep8, measuring code coverage, generating documentation, etc.) in order to better leverage its value.

One of its features is the creation/management of virtual environments, but this is only a means to facilitate testing, so it falls short in some aspects compared to other tools that can manage virtual environments, such as Virtualenvwrapper, conda, pipenv, poetry.

tox also has strong configurability and rich plugin support, which gives it a lot of possibilities and freedom in its use. As a result, it is still in continuous use by many loyal developers, for example, the author of the series of articles I just translated is one of its maintainers.

Finally, it should be added that tox uses configuration files as drivers, but they are quite cumbersome, so someone developed a nox similar to tox that uses Python files to do the configuration. This project is also very popular and has attracted many projects like pipx, urllib3, Salt, etc. If you are interested in this project, please check out：https://nox.thea.codes/en/stable