or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdconfiguration.mdenvironment-system.mdexecution-system.mdindex.mdplugin-system.mdsession-management.md
tile.json

tessl/pypi-tox

tox is a generic virtualenv management and test command line tool

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/tox@4.30.x

To install, run

npx @tessl/cli install tessl/pypi-tox@4.30.0

index.mddocs/

Tox

Tox is a generic virtualenv management and test command line tool for automating and standardizing testing in Python. It creates isolated virtual environments for testing Python packages under various configurations including different Python versions, implementations, and dependencies. Tox serves as both a command-line utility and a programmatically accessible library for test automation workflows.

Package Information

  • Package Name: tox
  • Language: Python
  • Installation: pip install tox
  • Version: 4.30.2
  • Documentation: https://tox.wiki

Core Imports

import tox
from tox import main

For programmatic access to key components:

from tox.run import main, run, setup_state
from tox.session.state import State
from tox.config.main import Config
from tox.tox_env.api import ToxEnv
from tox.plugin import impl

Basic Usage

Command Line Usage

# Run tests in default environments
tox

# Run specific environment
tox -e py311

# List available environments  
tox -l

# Run with custom configuration
tox -c custom-tox.ini

# Run in parallel
tox -p

Programmatic Usage

from tox.run import main

# Run tox programmatically with arguments
result = main(['--help'])

# Run specific environments
result = main(['-e', 'py311,py312'])

Plugin Development

from tox.plugin import impl
from tox.config.cli.parser import ToxParser

@impl
def tox_add_option(parser: ToxParser) -> None:
    parser.add_argument("--custom-flag", help="Add custom functionality")

@impl  
def tox_add_core_config(core_conf) -> None:
    core_conf.add_config(
        keys="custom_setting",
        desc="Custom configuration setting",
        of_type=str,
        default="default_value"
    )

Architecture

Tox follows a layered architecture designed for extensibility and flexibility:

  • CLI Layer: Command line parsing and user interface (tox.config.cli)
  • Session Layer: Coordination and state management (tox.session)
  • Configuration Layer: Configuration loading and management (tox.config)
  • Environment Layer: Virtual environment creation and management (tox.tox_env)
  • Execution Layer: Command execution within environments (tox.execute)
  • Plugin Layer: Extensibility through pluggy hooks (tox.plugin)

The State class serves as the central coordinator, providing access to configuration, environment selection, and execution state throughout the tox run lifecycle.

Capabilities

Core CLI Interface

Main entry points for command line and programmatic usage, including the primary main() function, CLI argument parsing, and execution coordination.

def main(args: Sequence[str]) -> int: ...
def run(args: Sequence[str] | None = None) -> None: ...
def setup_state(args: Sequence[str]) -> State: ...

Core CLI Interface

Configuration System

Comprehensive configuration management including file-based configuration (INI/TOML), programmatic configuration, and environment-specific settings. Supports configuration discovery, validation, and override mechanisms.

class Config:
    @classmethod
    def make(cls, parsed, pos_args, source, extended_envs) -> Config: ...
    def get_env(self, name: str) -> EnvConfigSet: ...
    def pos_args(self, to_path: Path | None) -> tuple[str, ...] | None: ...

class ConfigSet:
    def add_config(self, keys, desc, of_type, default=None, **kwargs): ...
    def load_config(self): ...

Configuration System

Session Management

Runtime state coordination through the State class and environment selection via EnvSelector. Controls the overall execution flow and provides access to configuration and environments.

class State:
    def __init__(self, options: Options, args: Sequence[str]) -> None: ...
    @property
    def envs(self) -> EnvSelector: ...
    @property
    def conf(self) -> Config: ...

class EnvSelector:
    def all(self) -> dict[str, ToxEnv]: ...
    def iter(self, only_active: bool = True) -> Iterator[tuple[str, ToxEnv]]: ...
    def get(self, item: str) -> ToxEnv: ...

Session Management

Environment System

Virtual environment creation, management, and lifecycle control. Supports different environment types including Python virtual environments, external environments, and custom environment implementations.

class ToxEnv:
    def __init__(self, create_args: ToxEnvCreateArgs) -> None: ...
    def setup(self) -> None: ...
    def teardown(self) -> None: ...
    def execute(self, request: ExecuteRequest) -> ExecuteStatus: ...
    @property
    def name(self) -> str: ...

class PythonToxEnv(ToxEnv):
    def python_executable(self) -> Path: ...
    def install_deps(self) -> None: ...

Environment System

Plugin System

Hook-based extensibility system using pluggy, allowing plugins to extend CLI options, configuration, environment types, and execution hooks. Supports both entry-point plugins and toxfile.py plugins.

impl: Callable[[_F], _F]  # Hook implementation decorator

class ToxHookSpecs:
    def tox_add_option(self, parser: ToxParser) -> None: ...
    def tox_add_core_config(self, core_conf) -> None: ...
    def tox_register_tox_env(self, register) -> None: ...
    def tox_before_run_commands(self, tox_env, run_conf, opts) -> None: ...

Plugin System

Execution System

Command execution infrastructure for running commands within tox environments, supporting subprocess execution, output capture, and execution status tracking.

class ExecuteRequest:
    def __init__(self, cmd, cwd=None, env=None, stdin=None, run_id=None): ...

class Execute:
    def __call__(self, request: ExecuteRequest) -> ExecuteStatus: ...

class ExecuteStatus:
    @property
    def exit_code(self) -> int: ...
    @property
    def out(self) -> str: ...
    @property
    def err(self) -> str: ...

Execution System

Common Types

Core Types

from typing import Sequence
from pathlib import Path

# Configuration types
class Parsed:
    """Parsed command line arguments"""
    
class Options:
    """Command line options container"""
    parsed: Parsed
    pos_args: Sequence[str] | None
    source: Source

# Error types  
class ToxError(Exception):
    """Base tox error"""

class HandledError(ToxError):
    """Error that should be handled gracefully"""

class Skip(ToxError):
    """Signal to skip an environment"""

Environment Types

# Environment registry
ENVIRONMENT_TYPES = {
    "python": "Virtual Python environment", 
    "pypy": "PyPy environment",
    "external": "External command environment"
}

# Common configuration keys
CONFIG_KEYS = {
    "basepython": "Base Python interpreter",
    "deps": "Dependencies to install", 
    "commands": "Commands to execute",
    "changedir": "Working directory",
    "install_command": "Package installation command"
}