DOCSEARCHbyAlgolia
Submit Docs

tox

repository·main·Indexed 26 days ago

https://github.com/tox-dev/tox

A generic virtualenv management and test command line tool used to automate and standardize Python testing. tox manages virtual environments to verify package builds and installs across multiple Python implementations, versions, and configurations, serving as a frontend for continuous integration (CI) servers.

Tokens
42K
Snippets
129
Records
292
Agent score
86%

What's inside tox

  1. Overview of tox

    main

    tox is a generic virtual environment management and test command line tool designed to automate and standardize Python testing. It helps developers:

    • Verify package builds and installs across different environments (e.g., different Python implementations, versions, or installation dependencies).
    • Run tests in multiple environments using a preferred test tool.
    • Act as a frontend for continuous integration (CI) servers to reduce boilerplate and unify CI with shell-based testing.

  2. Compare tox with nox and Invoke

    main

    If tox does not meet your requirements, consider these related projects:

    • nox: Similar to tox but uses Python scripts instead of a configuration file for setup. Useful if you find static configuration limiting.
    • Invoke: A general-purpose task execution library (similar to make). It is more general than tox and lacks Python testing-specific features.

  3. Project Overview and Technical Stack

    main
    tox is a Python-based automation tool (Python ≥ 3.10) used for managing environments and running tests. It uses hatchling as its build system and pluggy for its plugin framework. The project uses pytest for testing and Sphinx for documentation.

  4. Understand the post-release automation

    main

    Regardless of whether you use the local release method or the GitHub Actions method, both trigger a release.yaml workflow upon pushing a tag. This workflow automatically:

    1. Builds Python packages (sdist and wheel).
    2. Publishes the packages to PyPI using trusted publishing.

    Important Notes:

    • Both release methods involve a force-push to main; ensure no concurrent work is happening.
    • The release process is atomic and should not be interrupted.
    • If a release fails, it can be retried using the same version number.

  5. Understand the tox lifecycle

    main

    tox operates as an environment orchestrator through a specific lifecycle for each selected environment:

    1. Configuration: Loads configuration files (tox.toml, tox.ini, pyproject.toml, or toxfile.py) and merges them with CLI options and OS environment variables.
    2. Environment Creation: Creates a fresh environment (defaults to virtualenv). It automatically re-creates the environment if the Python version or dependencies change. Use the -r or --recreate flag to force recreation.
    3. Dependency Installation: Installs dependencies. If pylock is set, it uses a PEP 751 lock file. Otherwise, it installs deps and dependency_groups (defaults to pip).
    4. Packaging: Optionally builds and installs the current project.
    5. Extra Setup: Runs extra_setup_commands after installations but before test commands.
    6. Commands: Executes specified commands. If a command's exit code is non-zero, the environment fails unless the command starts with a dash (-) or commands_retry is configured.
    7. Report: Prints a summary of outcomes for all environments.

  6. Popular tox plugins

    main

    The following plugins are commonly used with tox:

    • tox-uv: Uses uv for faster package installation.
    • tox-gh-actions: Integrates tox with GitHub Actions for efficient CI workflows.
    • tox-gh: Enhanced GitHub integration for running tox across multiple environments.
    • tox-extra: Adds sanity checks (e.g., dirty repo detection, system dependencies) before/after tests.
    • tox-recreate: Automatically recreates environments when dependency files change.
    • tox-multipython: Provides interpreter discovery for multipython setups.

  7. Understand the tox Repository Layout

    main

    The repository is organized into several key subsystems:

    • src/tox/run.py: The main entry point.
    • src/tox/provision.py: Logic for self-provisioning.
    • src/tox/report.py: Logging and colored output.
    • src/tox/config/: Configuration subsystem, including CLI parsing (cli/), loaders (loader/), and discovery (source/).
    • src/tox/session/: Runtime state and built-in subcommands (cmd/).
    • src/tox/tox_env/: Environment classes, including Python-specific and virtualenv-based environments.
    • src/tox/execute/: Subprocess execution framework.
    • src/tox/plugin/: Integration with the pluggy plugin framework.
    • src/tox/journal/: JSON result journal.
    • src/tox/util/: Utility helpers (graph, cpu, path, etc.).

  8. Trace the tox Execution Flow

    main

    A typical tox run -e py311 command follows six main phases:

    1. Entry Point: CLI parsing, configuration loading, and state building.
    2. Provisioning: Checking if requirements are satisfied; if not, creating a provision environment and re-invoking tox.
    3. Discovery: Dispatching subcommands, discovering environments, and resolving dependencies.
    4. Environment Setup: Creating virtualenvs, installing dependencies, building/installing the package, and running extra_setup_commands.
    5. Execution: Running commands_pre, the main commands, and commands_post.
    6. Results: Collecting outcomes, writing to the journal, and reporting the summary.

  9. Use tox with PEP 517/518 build backends

    main

    tox automatically detects and uses the build backend specified in your pyproject.toml under the [build-system] table. No additional tox configuration is required for standard backends like Hatch, Flit, or PDM.

    [build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

  10. Configure Man Page support for Virtual Environments

    main
    When tox is installed inside a virtual environment (via pipx, uv tool, or venv), the man page is installed but not automatically added to the system MANPATH. Run the following command to set it up:
    tox man

  11. Create a tox configuration file

    main

    tox requires a configuration file at the project root to define tools and environments.

    TOML is the recommended format for new projects due to better type support and robustness. You can also generate a tox.ini automatically by running tox quickstart and following the prompts.

    TOML Example (tox.toml)

    env_list = ["3.13", "3.12", "lint"]

[env_run_base]
description = "run the test suite with pytest"
deps = [
    "pytest>=8",
]
commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]

[env.lint]
description = "run linters"
skip_install = true
deps = ["ruff"]
commands = [["ruff", "check", { replace = "posargs", default = [""], extend = true }]]

    INI Example (tox.ini)

    [tox]
env_list = 3.13, 3.12, lint

[testenv]
description = run the test suite with pytest
deps =
    pytest>=8
commands =
    pytest {posargs:tests}

[testenv:lint]
description = run linters
skip_install = true
deps =
    ruff
commands = ruff check {posargs:.}
    tox quickstart

  12. Implement External Plugins

    main

    External plugins are discovered via the tox entry point group. To create an external plugin, declare it in your package's pyproject.toml:

    [project.entry-points.tox]
my_plugin = "my_tox_plugin"

    You can disable specific external plugins by setting the TOX_DISABLED_EXTERNAL_PLUGINS environment variable to a comma-separated list of plugin names.