0
# Configuration Management
1
2
Flexible configuration system supporting multiple file formats (TOML, INI) and command-line overrides. Handles check selection, package expectations, directory traversal patterns, and integration with various project configuration files.
3
4
## Capabilities
5
6
### Configuration Loading
7
8
Automatic discovery and parsing of configuration files in multiple formats, with support for project-specific settings and hierarchical configuration resolution.
9
10
```python { .api }
11
class Configuration:
12
"""Container for WheelChecker configuration values"""
13
14
def __init__(self, select: set[Check] | None = None,
15
ignore: set[Check] | None = None,
16
toplevel: list[str] | None = None,
17
package_paths: list[Path] | None = None,
18
src_dirs: list[Path] | None = None,
19
package_omit: list[str] | None = None):
20
"""
21
Initialize configuration container.
22
23
Parameters:
24
- select: Set of checks to enable, or None for default
25
- ignore: Set of checks to disable, or None for none
26
- toplevel: Expected toplevel library entries for W2 checks
27
- package_paths: Paths specified with --package option
28
- src_dirs: Paths specified with --src-dir option
29
- package_omit: Patterns to exclude when traversing package/src dirs
30
"""
31
32
@classmethod
33
def from_config_file(cls, path: str | None = None) -> 'Configuration':
34
"""
35
Read configuration from file or discover automatically.
36
37
Parameters:
38
- configpath: Explicit config file path, or None to auto-discover
39
40
Returns:
41
Configuration instance with loaded settings
42
43
Raises:
44
- UserInputError: If config file is invalid or contains errors
45
"""
46
47
@classmethod
48
def from_command_options(cls, select: set[Check] | None = None,
49
ignore: set[Check] | None = None,
50
toplevel: list[str] | None = None,
51
package: tuple[str, ...] = (),
52
src_dir: tuple[str, ...] = (),
53
package_omit: list[str] | None = None) -> 'Configuration':
54
"""Construct Configuration from command line options"""
55
```
56
57
### File Format Support
58
59
Support for multiple configuration file formats with automatic format detection and parsing.
60
61
```python { .api }
62
# Configuration file search order (first found with relevant section is used)
63
CONFIG_FILES = [
64
"pyproject.toml", # TOML format in [tool.check-wheel-contents]
65
"tox.ini", # INI format in [check-wheel-contents]
66
"setup.cfg", # INI format in [tool:check-wheel-contents]
67
"check-wheel-contents.cfg", # INI format in [check-wheel-contents]
68
".check-wheel-contents.cfg" # INI format in [check-wheel-contents]
69
]
70
71
CONFIG_SECTION = "check-wheel-contents" # Default INI section name
72
73
# Default exclusion patterns for package/src-dir traversal
74
TRAVERSAL_EXCLUSIONS = [
75
".*", "CVS", "RCS", "*.pyc", "*.pyo", "*.egg-info"
76
]
77
```
78
79
### Package Tree Building
80
81
Functionality for building expected package structures from source directories and package specifications.
82
83
```python { .api }
84
def build_package_tree(self, package_paths: list[Path],
85
src_dir_paths: list[Path],
86
package_omit: list[str] | None = None) -> Directory:
87
"""
88
Build expected package tree from source paths.
89
90
Parameters:
91
- package_paths: List of package directories to include
92
- src_dir_paths: List of source directories to include contents of
93
- package_omit: Patterns to exclude during traversal
94
95
Returns:
96
Directory representing expected package structure
97
98
Raises:
99
- UserInputError: If paths are invalid or inaccessible
100
"""
101
102
def traverse_tree(self, dirpath: Path,
103
exclusions: list[str] | None = None) -> Directory:
104
"""
105
Traverse a directory tree with exclusion patterns.
106
107
Parameters:
108
- dirpath: Root directory to traverse
109
- exclusions: Glob patterns to exclude
110
111
Returns:
112
Directory tree representation
113
"""
114
```
115
116
### Usage Examples
117
118
```python
119
from pathlib import Path
120
from check_wheel_contents.config import Configuration, CONFIG_FILES
121
from check_wheel_contents.errors import UserInputError
122
123
# Auto-discover configuration
124
try:
125
config = Configuration.read_config()
126
print(f"Loaded configuration from auto-discovered file")
127
except UserInputError as e:
128
print(f"Configuration error: {e}")
129
130
# Load from specific file
131
config_path = Path("pyproject.toml")
132
if config_path.exists():
133
config = Configuration.read_config(config_path)
134
print(f"Loaded configuration from {config_path}")
135
136
# Create configuration programmatically
137
from check_wheel_contents.checks import parse_checks_string
138
139
config = Configuration(
140
select=parse_checks_string("W1,W2"),
141
ignore=parse_checks_string("W005"),
142
toplevel=["mypackage"],
143
package_paths=[Path("src/mypackage")],
144
package_omit=["*.pyc", ".*", "__pycache__"]
145
)
146
147
# Check configuration values
148
selected = config.get_checks_selected()
149
if selected:
150
print(f"Selected checks: {[c.name for c in selected]}")
151
152
ignored = config.get_checks_ignored()
153
if ignored:
154
print(f"Ignored checks: {[c.name for c in ignored]}")
155
156
# Example pyproject.toml configuration:
157
"""
158
[tool.check-wheel-contents]
159
select = ["W1", "W2"]
160
ignore = ["W005"]
161
toplevel = ["mypackage", "mypackage.ext"]
162
package = ["src/mypackage"]
163
src-dir = ["src"]
164
package-omit = ["*.pyc", ".*", "__pycache__", "tests"]
165
"""
166
167
# Example setup.cfg configuration:
168
"""
169
[tool:check-wheel-contents]
170
select = W1,W2
171
ignore = W005
172
toplevel = mypackage,mypackage.ext
173
package = src/mypackage
174
src-dir = src
175
package-omit = *.pyc,.*,__pycache__,tests
176
"""
177
178
# Manual configuration file discovery
179
for filename in CONFIG_FILES:
180
config_path = Path(filename)
181
if config_path.exists():
182
try:
183
config = Configuration.read_config(config_path)
184
print(f"Using config from {filename}")
185
break
186
except UserInputError:
187
continue
188
else:
189
print("No configuration file found, using defaults")
190
config = Configuration()
191
```