You no longer have to tell me, use Tox!!!

Content

• Introduction
• Python and OS Compatibility
• User Guide
• Key Tox Features
• Tox in Action
  • Installation
  • Configuration
  • Running Tox
• Why You Can't Afford to Skip Tox
• Conclusion

Introduction

Tox is a versatile and powerful command-line tool designed for Python projects, enabling developers to automate various tasks, including testing, building, packaging, and deployment across different environments. This article will walk you through the key features of Tox and demonstrate how to use it effectively in your Python development workflow.

Python and OS Compatibility

Tox supports a range of Python interpreter implementations, including CPython versions 3.7, 3.8, 3.9, 3.10, and 3.11. This ensures that Tox can be used with the latest patch versions of these minor Python versions, with best-effort support for previous patch versions.

User Guide

Tox serves as an environment orchestrator, allowing you to set up and execute various tools for your projects. It can handle tasks such as:

• Running test runners like pytest.
• Linting your code with tools like flake8.
• Formatting code using tools like black or isort.
• Generating documentation with Sphinx.
• Building and publishing packages with tools like twine.

Key Tox Features

Tox offers several key features that make it an indispensable tool for Python development:

• Testing Across Environments: Tox allows you to test your Python code across different environments, including various Python versions and dependencies. This ensures your code works consistently across different setups.

• Virtual Environment Management: Tox manages the creation and management of virtual environments, eliminating issues related to environment setup.

• Integration with CI: You can use Tox as a frontend for continuous integration (CI) servers, reducing boilerplate and seamlessly integrating shell-based testing.

• Customization: Tox offers extensive customization options, allowing you to tailor every aspect of virtual environments and command execution to your project's needs.

• Parallel Testing: Tox can run multiple environments in parallel, speeding up the testing process.

Tox in Action

Here's a quick overview of how Tox works:

1. Tox generates a series of virtual environments for different configurations.
2. It installs the required dependencies for each environment.
3. Tox runs setup commands defined in the configuration for each environment.
4. The results from each environment are returned to the user.

Now, walk with me through your first Tox script

Installation:

To get started with Tox, you'll need to install it first. It's recommended to use pipx to install Tox in an isolated environment, allowing for easy upgrades without affecting other parts of your system.

python -m pip install pipx --user
pipx install tox

Once Tox is installed, you can check its help documentation using the tox --help command.

Configuration:

Tox configuration can be defined in several places, with priority given to the following order:

1. tox.ini
2. pyproject.toml
3. setup.cfg

Here's a basic example of a tox.ini file:

[tox]
envlist = my_env
skipsdist = true

[testenv]
deps = pytest
commands = pytest

In this example, we define a single test environment named my_env. The skipsdist setting is used when you're not testing a Python package.

Running Tox:

After configuring tox.ini, you can run Tox by executing the tox command. Tox will create virtual environments, install dependencies, and execute the defined test commands.

tox

Here's a more typical sample configuration for Tox from rent predictor (a project on my github), which illustrates how to define different environments and their settings:

# Tox Configuration File

# Min version of Tox required for this configuration
[tox]
min_version = 4

# List of environments to be run by default
envlist = run, checks

# Flag to skip packaging operations as this is not a Python package
skipsdist = True

# Environment definitions and settings

# Default settings for the test environments
[testenv]
install_command = pip install {opts} {packages}

# Environment to install dependencies and run the uvicorn server
[testenv:run]
description = Install dependencies and run uvicorn server
deps =
    -rrequirements/test_requirements.txt
setenv =
    PYTHONPATH=.
    PYTHONHASHSEED=0
commands=
    python app/main.py

# Environment for running code checks (linters, formatting, and mypy)
[testenv:checks]
envdir = {toxworkdir}/checks
deps =
    -r{toxinidir}/requirements/typing_requirements.txt
commands =
    flake8 app
    isort app
    black app
    {posargs:mypy app}

# Flake8 settings for code linting
[flake8]
exclude = .git,__pycache__,__init__.py,.mypy_cache,.pytest_cache,.venv,venv,alembic
max-line-length = 88

Comments explaining the different sections:

1. [tox]: Defines global settings for Tox.

   • min_version: Specifies the minimum Tox version required.
   • envlist: Lists the default environments to be run.
   • skipsdist: Flag to skip packaging operations, useful when the project isn't a Python package.

2. [testenv]: Default settings for the test environments.

   • install_command: Custom command for installing dependencies.

3. [testenv:run]: Environment to install dependencies and run the uvicorn server.

   • description: A description of the purpose of this environment.
   • deps: Specifies dependencies needed for this environment.
   • setenv: Sets environment variables.
   • commands: Command to run the main application.

4. [testenv:checks]: Environment for running code checks.

   • envdir: Directory for the environment.
   • deps: Dependencies needed for linting and typing checks.
   • commands: Commands to run various code checkers such as flake8, isort, black, and mypy.

5. [flake8]: Configuration for Flake8 (code linter).

   • exclude: Directories and files to be excluded during linting.
   • max-line-length: Maximum line length allowed.

The configuration file includes sections for different environments, defining their purposes, dependencies, and commands to execute.

This code doesn’t implement testing and CI, so watch out for my next post, as that will implement testing with Pytest, CI with github actions and some other deployment best practices.

Why You Can't Afford to Skip Tox:

Still not convinced? If you neglect Tox, your Python project may continue to be a chaotic mess. The "it works on my machine" excuse will plague your team, causing endless frustration. Tox is your ticket to harmony in Python development, ensuring that your code performs flawlessly on various Python versions and environments.

Conclusion

Tox is an essential tool for Python developers, supercharging the testing and development process. By using Tox, you can ensure your Python code is robust and works across various Python versions and dependencies. Its customization options and compatibility with CI systems make it a valuable addition to your development toolkit. So, start using Tox today to enhance your Python development workflow.