0
# Tox
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: tox
7
- **Language**: Python  
8
- **Installation**: `pip install tox`
9
- **Version**: 4.30.2
10
- **Documentation**: https://tox.wiki
11

12
## Core Imports
13

14
```python
15
import tox
16
from tox import main
17
```
18

19
For programmatic access to key components:
20

21
```python
22
from tox.run import main, run, setup_state
23
from tox.session.state import State
24
from tox.config.main import Config
25
from tox.tox_env.api import ToxEnv
26
from tox.plugin import impl
27
```
28

29
## Basic Usage
30

31
### Command Line Usage
32

33
```bash
34
# Run tests in default environments
35
tox
36

37
# Run specific environment
38
tox -e py311
39

40
# List available environments  
41
tox -l
42

43
# Run with custom configuration
44
tox -c custom-tox.ini
45

46
# Run in parallel
47
tox -p
48
```
49

50
### Programmatic Usage
51

52
```python
53
from tox.run import main
54

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

58
# Run specific environments
59
result = main(['-e', 'py311,py312'])
60
```
61

62
### Plugin Development
63

64
```python
65
from tox.plugin import impl
66
from tox.config.cli.parser import ToxParser
67

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

72
@impl  
73
def tox_add_core_config(core_conf) -> None:
74
    core_conf.add_config(
75
        keys="custom_setting",
76
        desc="Custom configuration setting",
77
        of_type=str,
78
        default="default_value"
79
    )
80
```
81

82
## Architecture
83

84
Tox follows a layered architecture designed for extensibility and flexibility:
85

86
- **CLI Layer**: Command line parsing and user interface (`tox.config.cli`)
87
- **Session Layer**: Coordination and state management (`tox.session`)  
88
- **Configuration Layer**: Configuration loading and management (`tox.config`)
89
- **Environment Layer**: Virtual environment creation and management (`tox.tox_env`)
90
- **Execution Layer**: Command execution within environments (`tox.execute`)
91
- **Plugin Layer**: Extensibility through pluggy hooks (`tox.plugin`)
92

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

95
## Capabilities
96

97
### Core CLI Interface
98

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

101
```python { .api }
102
def main(args: Sequence[str]) -> int: ...
103
def run(args: Sequence[str] | None = None) -> None: ...
104
def setup_state(args: Sequence[str]) -> State: ...
105
```
106

107
[Core CLI Interface](./cli-interface.md)
108

109
### Configuration System
110

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

113
```python { .api }
114
class Config:
115
    @classmethod
116
    def make(cls, parsed, pos_args, source, extended_envs) -> Config: ...
117
    def get_env(self, name: str) -> EnvConfigSet: ...
118
    def pos_args(self, to_path: Path | None) -> tuple[str, ...] | None: ...
119

120
class ConfigSet:
121
    def add_config(self, keys, desc, of_type, default=None, **kwargs): ...
122
    def load_config(self): ...
123
```
124

125
[Configuration System](./configuration.md)
126

127
### Session Management
128

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

131
```python { .api }
132
class State:
133
    def __init__(self, options: Options, args: Sequence[str]) -> None: ...
134
    @property
135
    def envs(self) -> EnvSelector: ...
136
    @property
137
    def conf(self) -> Config: ...
138

139
class EnvSelector:
140
    def all(self) -> dict[str, ToxEnv]: ...
141
    def iter(self, only_active: bool = True) -> Iterator[tuple[str, ToxEnv]]: ...
142
    def get(self, item: str) -> ToxEnv: ...
143
```
144

145
[Session Management](./session-management.md)
146

147
### Environment System
148

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

151
```python { .api }
152
class ToxEnv:
153
    def __init__(self, create_args: ToxEnvCreateArgs) -> None: ...
154
    def setup(self) -> None: ...
155
    def teardown(self) -> None: ...
156
    def execute(self, request: ExecuteRequest) -> ExecuteStatus: ...
157
    @property
158
    def name(self) -> str: ...
159

160
class PythonToxEnv(ToxEnv):
161
    def python_executable(self) -> Path: ...
162
    def install_deps(self) -> None: ...
163
```
164

165
[Environment System](./environment-system.md)
166

167
### Plugin System
168

169
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.
170

171
```python { .api }
172
impl: Callable[[_F], _F]  # Hook implementation decorator
173

174
class ToxHookSpecs:
175
    def tox_add_option(self, parser: ToxParser) -> None: ...
176
    def tox_add_core_config(self, core_conf) -> None: ...
177
    def tox_register_tox_env(self, register) -> None: ...
178
    def tox_before_run_commands(self, tox_env, run_conf, opts) -> None: ...
179
```
180

181
[Plugin System](./plugin-system.md)
182

183
### Execution System
184

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

187
```python { .api }
188
class ExecuteRequest:
189
    def __init__(self, cmd, cwd=None, env=None, stdin=None, run_id=None): ...
190

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

194
class ExecuteStatus:
195
    @property
196
    def exit_code(self) -> int: ...
197
    @property
198
    def out(self) -> str: ...
199
    @property
200
    def err(self) -> str: ...
201
```
202

203
[Execution System](./execution-system.md)
204

205
## Common Types
206

207
### Core Types
208

209
```python { .api }
210
from typing import Sequence
211
from pathlib import Path
212

213
# Configuration types
214
class Parsed:
215
    """Parsed command line arguments"""
216
    
217
class Options:
218
    """Command line options container"""
219
    parsed: Parsed
220
    pos_args: Sequence[str] | None
221
    source: Source
222

223
# Error types  
224
class ToxError(Exception):
225
    """Base tox error"""
226

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

230
class Skip(ToxError):
231
    """Signal to skip an environment"""
232
```
233

234
### Environment Types
235

236
```python { .api }
237
# Environment registry
238
ENVIRONMENT_TYPES = {
239
    "python": "Virtual Python environment", 
240
    "pypy": "PyPy environment",
241
    "external": "External command environment"
242
}
243

244
# Common configuration keys
245
CONFIG_KEYS = {
246
    "basepython": "Base Python interpreter",
247
    "deps": "Dependencies to install", 
248
    "commands": "Commands to execute",
249
    "changedir": "Working directory",
250
    "install_command": "Package installation command"
251
}
252
```