tessl/pypi-tox

tox is a generic virtualenv management and test command line tool

Overview

Eval results

Files

Configuration System

Name: tessl/pypi-tox
Author: tessl

Comprehensive configuration management for tox, supporting file-based configuration (INI/TOML), programmatic configuration, and environment-specific settings. The configuration system provides discovery, validation, override mechanisms, and extensibility through plugins.

Capabilities

Main Configuration Class

The central configuration object that manages all tox settings, environment configurations, and runtime options.

class Config:
    """Main configuration object for tox."""
    
    @classmethod
    def make(cls, parsed: Parsed, pos_args: Sequence[str] | None, 
             source: Source, extra_envs: Iterable[str]) -> Config:
        """
        Create a configuration instance.
        
        Args:
            parsed: Parsed command line arguments
            pos_args: Positional arguments
            source: Configuration source (file path or discovery result)
            extra_envs: Additional environments from plugins
            
        Returns:
            Config: Configured instance
        """
    
    def get_env(self, item: str, package: bool = False, 
                loaders: Sequence[Loader[Any]] | None = None) -> EnvConfigSet:
        """
        Get environment-specific configuration.
        
        Args:
            item: Environment name (e.g., 'py311', 'docs')
            package: Flag indicating if environment is packaging type
            loaders: Loaders to use for this configuration
            
        Returns:
            EnvConfigSet: Environment configuration
        """
    
    def pos_args(self, to_path: Path | None) -> tuple[str, ...] | None:
        """
        Get positional arguments relative to specified path.
        
        Args:
            to_path: Base path for relative arguments
            
        Returns:
            tuple[str, ...] | None: Positional arguments or None
        """
    
    @property
    def core(self) -> CoreConfigSet:
        """Core tox configuration settings."""
    
    @property
    def work_dir(self) -> Path:
        """Working directory for tox operations."""
        
    @property
    def src_path(self) -> Path:
        """Path to the tox configuration source."""
        
    @property
    def options(self) -> Parsed:
        """Parsed command line options."""
        
    def sections(self) -> Iterator[Section]:
        """Iterate over configuration sections."""
        
    def clear_env(self, name: str) -> None:
        """Clear cached environment configuration."""
        
    memory_seed_loaders: defaultdict[str, list[MemoryLoader]]
    """Memory-based configuration loaders."""

Configuration Sets

Base classes for organizing configuration settings into logical groups.

class ConfigSet:
    """Base configuration set for organizing related settings."""
    
    def add_config(self, keys: str | list[str], desc: str, of_type: type, 
                   default=None, **kwargs) -> None:
        """
        Add a configuration option.
        
        Args:
            keys: Configuration key(s)
            desc: Description of the setting
            of_type: Expected type
            default: Default value
            **kwargs: Additional configuration options
        """
    
    def load_config(self) -> None:
        """Load and validate configuration values."""

class CoreConfigSet(ConfigSet):
    """Core tox configuration settings."""
    
    def add_constant(self, keys: str | list[str], desc: str, value) -> None:
        """
        Add a constant configuration value.
        
        Args:
            keys: Configuration key(s)
            desc: Description
            value: Constant value
        """

class EnvConfigSet(ConfigSet):
    """Environment-specific configuration settings."""
    
    @property
    def name(self) -> str:
        """Environment name."""

Configuration Loaders

Classes responsible for loading configuration from different sources.

class Loader:
    """Base configuration loader."""
    
    def load(self, key: str, of_type: type, default=None) -> Any:
        """
        Load configuration value.
        
        Args:
            key: Configuration key
            of_type: Expected type
            default: Default value if not found
            
        Returns:
            Any: Configuration value
        """

class IniLoader(Loader):
    """Load configuration from INI files (tox.ini, setup.cfg)."""

class TomlLoader(Loader):
    """Load configuration from TOML files (pyproject.toml)."""
    
class MemoryLoader(Loader):
    """Load configuration from in-memory settings."""

Configuration Sources

Classes for discovering and managing configuration file sources.

class Source:
    """Configuration source abstraction."""
    
    @property
    def path(self) -> Path:
        """Path to configuration source."""
        
    @property
    def exists(self) -> bool:
        """Whether source exists."""

def discover_source(path: Path) -> Source:
    """
    Discover configuration source starting from path.
    
    Args:
        path: Starting path for discovery
        
    Returns:
        Source: Discovered configuration source
    """

CLI Configuration

Command line parsing and option management.

class ToxParser:
    """Command line parser for tox."""
    
    def add_argument(self, *args, **kwargs) -> None:
        """Add command line argument."""

class Options:
    """Container for parsed command line options."""
    
    @property
    def parsed(self) -> Parsed:
        """Parsed command line arguments."""
        
    @property
    def pos_args(self) -> Sequence[str] | None:
        """Positional arguments."""
        
    @property
    def source(self) -> Source:
        """Configuration source."""

def get_options(*args: str) -> Options:
    """
    Parse command line arguments.
    
    Args:
        *args: Command line arguments
        
    Returns:
        Options: Parsed options
    """

Configuration File Formats

INI Format (tox.ini, setup.cfg)

[tox]
envlist = py311,py312,docs
skip_missing_interpreters = true

[testenv]
deps = pytest>=6.0
       pytest-cov
commands = pytest {posargs}
passenv = CI

[testenv:docs]
deps = sphinx
       sphinx-rtd-theme  
commands = sphinx-build -b html docs docs/_build/html

TOML Format (pyproject.toml)

[tool.tox]
legacy_tox_ini = """
[tox]
envlist = py311,py312,docs

[testenv]
deps = pytest>=6.0
       pytest-cov
commands = pytest {posargs}
"""

Core Configuration Options

Global Options ([tox] section)

envlist: List of environments to run by default
skip_missing_interpreters: Skip missing Python interpreters
work_dir: Working directory for tox operations
temp_dir: Temporary directory
package_dir: Directory containing the package
min_version: Minimum required tox version

Environment Options ([testenv] section)

basepython: Base Python interpreter
deps: Dependencies to install
commands: Commands to execute
commands_pre: Commands to run before main commands
commands_post: Commands to run after main commands
install_command: Package installation command
changedir: Working directory for commands
passenv: Environment variables to pass through
setenv: Environment variables to set
allowlist_externals: Allowed external commands
skip_install: Skip package installation

Package Options

package: Package type (wheel, sdist, skip)
build_dir: Build directory
package_env: Environment for package building
wheel_build_env: Environment for wheel building

Configuration Override

Override configuration values from command line:

# Override single value
tox --override testenv.deps=pytest>=7.0

# Override multiple values  
tox --override testenv.commands="pytest -v" --override tox.skip_missing_interpreters=false

Programmatic override:

from tox.config.main import Config

# Create config with overrides
config = Config.make(parsed_args, pos_args, source, extended_envs)

# Access overridden values
env_config = config.get_env('py311')
deps = env_config['deps']

Configuration Discovery

Tox searches for configuration in this order:

tox.ini (preferred)
pyproject.toml with [tool.tox] section
setup.cfg with [tox:tox] section

Discovery starts from current directory and searches up the directory tree until a configuration file is found.

Plugin Configuration Extensions

Plugins can extend configuration through hooks:

from tox.plugin import impl

@impl
def tox_add_core_config(core_conf: CoreConfigSet) -> None:
    """Add core configuration options."""
    core_conf.add_config(
        keys="custom_option",
        desc="Custom plugin option",
        of_type=str,
        default="default_value"
    )

@impl  
def tox_add_env_config(env_conf: EnvConfigSet) -> None:
    """Add environment configuration options."""
    env_conf.add_config(
        keys="env_custom_option", 
        desc="Custom environment option",
        of_type=bool,
        default=False
    )

Install with Tessl CLI