0
# Configuration System
1
2
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.
3
4
## Capabilities
5
6
### Main Configuration Class
7
8
The central configuration object that manages all tox settings, environment configurations, and runtime options.
9
10
```python { .api }
11
class Config:
12
"""Main configuration object for tox."""
13
14
@classmethod
15
def make(cls, parsed: Parsed, pos_args: Sequence[str] | None,
16
source: Source, extra_envs: Iterable[str]) -> Config:
17
"""
18
Create a configuration instance.
19
20
Args:
21
parsed: Parsed command line arguments
22
pos_args: Positional arguments
23
source: Configuration source (file path or discovery result)
24
extra_envs: Additional environments from plugins
25
26
Returns:
27
Config: Configured instance
28
"""
29
30
def get_env(self, item: str, package: bool = False,
31
loaders: Sequence[Loader[Any]] | None = None) -> EnvConfigSet:
32
"""
33
Get environment-specific configuration.
34
35
Args:
36
item: Environment name (e.g., 'py311', 'docs')
37
package: Flag indicating if environment is packaging type
38
loaders: Loaders to use for this configuration
39
40
Returns:
41
EnvConfigSet: Environment configuration
42
"""
43
44
def pos_args(self, to_path: Path | None) -> tuple[str, ...] | None:
45
"""
46
Get positional arguments relative to specified path.
47
48
Args:
49
to_path: Base path for relative arguments
50
51
Returns:
52
tuple[str, ...] | None: Positional arguments or None
53
"""
54
55
@property
56
def core(self) -> CoreConfigSet:
57
"""Core tox configuration settings."""
58
59
@property
60
def work_dir(self) -> Path:
61
"""Working directory for tox operations."""
62
63
@property
64
def src_path(self) -> Path:
65
"""Path to the tox configuration source."""
66
67
@property
68
def options(self) -> Parsed:
69
"""Parsed command line options."""
70
71
def sections(self) -> Iterator[Section]:
72
"""Iterate over configuration sections."""
73
74
def clear_env(self, name: str) -> None:
75
"""Clear cached environment configuration."""
76
77
memory_seed_loaders: defaultdict[str, list[MemoryLoader]]
78
"""Memory-based configuration loaders."""
79
```
80
81
### Configuration Sets
82
83
Base classes for organizing configuration settings into logical groups.
84
85
```python { .api }
86
class ConfigSet:
87
"""Base configuration set for organizing related settings."""
88
89
def add_config(self, keys: str | list[str], desc: str, of_type: type,
90
default=None, **kwargs) -> None:
91
"""
92
Add a configuration option.
93
94
Args:
95
keys: Configuration key(s)
96
desc: Description of the setting
97
of_type: Expected type
98
default: Default value
99
**kwargs: Additional configuration options
100
"""
101
102
def load_config(self) -> None:
103
"""Load and validate configuration values."""
104
105
class CoreConfigSet(ConfigSet):
106
"""Core tox configuration settings."""
107
108
def add_constant(self, keys: str | list[str], desc: str, value) -> None:
109
"""
110
Add a constant configuration value.
111
112
Args:
113
keys: Configuration key(s)
114
desc: Description
115
value: Constant value
116
"""
117
118
class EnvConfigSet(ConfigSet):
119
"""Environment-specific configuration settings."""
120
121
@property
122
def name(self) -> str:
123
"""Environment name."""
124
```
125
126
### Configuration Loaders
127
128
Classes responsible for loading configuration from different sources.
129
130
```python { .api }
131
class Loader:
132
"""Base configuration loader."""
133
134
def load(self, key: str, of_type: type, default=None) -> Any:
135
"""
136
Load configuration value.
137
138
Args:
139
key: Configuration key
140
of_type: Expected type
141
default: Default value if not found
142
143
Returns:
144
Any: Configuration value
145
"""
146
147
class IniLoader(Loader):
148
"""Load configuration from INI files (tox.ini, setup.cfg)."""
149
150
class TomlLoader(Loader):
151
"""Load configuration from TOML files (pyproject.toml)."""
152
153
class MemoryLoader(Loader):
154
"""Load configuration from in-memory settings."""
155
```
156
157
### Configuration Sources
158
159
Classes for discovering and managing configuration file sources.
160
161
```python { .api }
162
class Source:
163
"""Configuration source abstraction."""
164
165
@property
166
def path(self) -> Path:
167
"""Path to configuration source."""
168
169
@property
170
def exists(self) -> bool:
171
"""Whether source exists."""
172
173
def discover_source(path: Path) -> Source:
174
"""
175
Discover configuration source starting from path.
176
177
Args:
178
path: Starting path for discovery
179
180
Returns:
181
Source: Discovered configuration source
182
"""
183
```
184
185
### CLI Configuration
186
187
Command line parsing and option management.
188
189
```python { .api }
190
class ToxParser:
191
"""Command line parser for tox."""
192
193
def add_argument(self, *args, **kwargs) -> None:
194
"""Add command line argument."""
195
196
class Options:
197
"""Container for parsed command line options."""
198
199
@property
200
def parsed(self) -> Parsed:
201
"""Parsed command line arguments."""
202
203
@property
204
def pos_args(self) -> Sequence[str] | None:
205
"""Positional arguments."""
206
207
@property
208
def source(self) -> Source:
209
"""Configuration source."""
210
211
def get_options(*args: str) -> Options:
212
"""
213
Parse command line arguments.
214
215
Args:
216
*args: Command line arguments
217
218
Returns:
219
Options: Parsed options
220
"""
221
```
222
223
## Configuration File Formats
224
225
### INI Format (tox.ini, setup.cfg)
226
227
```ini
228
[tox]
229
envlist = py311,py312,docs
230
skip_missing_interpreters = true
231
232
[testenv]
233
deps = pytest>=6.0
234
pytest-cov
235
commands = pytest {posargs}
236
passenv = CI
237
238
[testenv:docs]
239
deps = sphinx
240
sphinx-rtd-theme
241
commands = sphinx-build -b html docs docs/_build/html
242
```
243
244
### TOML Format (pyproject.toml)
245
246
```toml
247
[tool.tox]
248
legacy_tox_ini = """
249
[tox]
250
envlist = py311,py312,docs
251
252
[testenv]
253
deps = pytest>=6.0
254
pytest-cov
255
commands = pytest {posargs}
256
"""
257
```
258
259
## Core Configuration Options
260
261
### Global Options ([tox] section)
262
263
- `envlist`: List of environments to run by default
264
- `skip_missing_interpreters`: Skip missing Python interpreters
265
- `work_dir`: Working directory for tox operations
266
- `temp_dir`: Temporary directory
267
- `package_dir`: Directory containing the package
268
- `min_version`: Minimum required tox version
269
270
### Environment Options ([testenv] section)
271
272
- `basepython`: Base Python interpreter
273
- `deps`: Dependencies to install
274
- `commands`: Commands to execute
275
- `commands_pre`: Commands to run before main commands
276
- `commands_post`: Commands to run after main commands
277
- `install_command`: Package installation command
278
- `changedir`: Working directory for commands
279
- `passenv`: Environment variables to pass through
280
- `setenv`: Environment variables to set
281
- `allowlist_externals`: Allowed external commands
282
- `skip_install`: Skip package installation
283
284
### Package Options
285
286
- `package`: Package type (wheel, sdist, skip)
287
- `build_dir`: Build directory
288
- `package_env`: Environment for package building
289
- `wheel_build_env`: Environment for wheel building
290
291
## Configuration Override
292
293
Override configuration values from command line:
294
295
```bash
296
# Override single value
297
tox --override testenv.deps=pytest>=7.0
298
299
# Override multiple values
300
tox --override testenv.commands="pytest -v" --override tox.skip_missing_interpreters=false
301
```
302
303
Programmatic override:
304
305
```python
306
from tox.config.main import Config
307
308
# Create config with overrides
309
config = Config.make(parsed_args, pos_args, source, extended_envs)
310
311
# Access overridden values
312
env_config = config.get_env('py311')
313
deps = env_config['deps']
314
```
315
316
## Configuration Discovery
317
318
Tox searches for configuration in this order:
319
320
1. `tox.ini` (preferred)
321
2. `pyproject.toml` with `[tool.tox]` section
322
3. `setup.cfg` with `[tox:tox]` section
323
324
Discovery starts from current directory and searches up the directory tree until a configuration file is found.
325
326
## Plugin Configuration Extensions
327
328
Plugins can extend configuration through hooks:
329
330
```python
331
from tox.plugin import impl
332
333
@impl
334
def tox_add_core_config(core_conf: CoreConfigSet) -> None:
335
"""Add core configuration options."""
336
core_conf.add_config(
337
keys="custom_option",
338
desc="Custom plugin option",
339
of_type=str,
340
default="default_value"
341
)
342
343
@impl
344
def tox_add_env_config(env_conf: EnvConfigSet) -> None:
345
"""Add environment configuration options."""
346
env_conf.add_config(
347
keys="env_custom_option",
348
desc="Custom environment option",
349
of_type=bool,
350
default=False
351
)
352
```