0
# Configuration
1

2
Comprehensive configuration system that handles command-line arguments, profiles, tool settings, and environment detection. The ProspectorConfig class is the central configuration management system for Prospector.
3

4
## Capabilities
5

6
### ProspectorConfig Class
7

8
Main configuration class that aggregates settings from command-line arguments, configuration files, and profiles.
9

10
```python { .api }
11
class ProspectorConfig:
12
    def __init__(self, workdir: Optional[Path] = None) -> None
13
```
14

15
Creates a new configuration instance by processing command-line arguments and loading profiles.
16

17
**Parameters:**
18
- `workdir`: Optional[Path] - Working directory for analysis (defaults to current directory)
19

20
**Properties:**
21
- `paths`: list[Path] - Paths to analyze (files or directories)
22
- `workdir`: Path - Working directory for the analysis
23
- `profile`: ProspectorProfile - Active configuration profile
24
- `tools_to_run`: list[str] - List of tool names to execute
25
- `libraries`: list[str] - Detected/configured libraries (Django, Flask, etc.)
26
- `messages`: list[Message] - Configuration-related messages and warnings
27
- `explicit_file_mode`: bool - True if analyzing specific files rather than directories
28
- `ignores`: list[re.Pattern[str]] - Compiled regex patterns for ignoring files/paths
29
- `configured_by`: dict[str, Optional[Union[str, Path]]] - Track how each tool was configured
30

31
### Tool Management
32

33
```python { .api }
34
def get_tools(self, found_files: FileFinder) -> list[tools.ToolBase]
35
```
36

37
Creates and configures all enabled analysis tools.
38

39
**Parameters:**
40
- `found_files`: FileFinder - File discovery object for tool configuration
41

42
**Returns:**
43
- `list[tools.ToolBase]` - List of configured and ready-to-run tools
44

45
**Side Effects:**
46
- Updates `configured_by` dictionary with tool configuration sources
47
- Adds configuration messages to `messages` list
48

49
```python { .api }
50
def replace_deprecated_tool_names(self) -> list[str]
51
```
52

53
Replaces deprecated tool names (pep8→pycodestyle, pep257→pydocstyle) with current names.
54

55
**Returns:**
56
- `list[str]` - List of deprecated tool names that were found and replaced
57

58
### File Filtering
59

60
```python { .api }
61
def make_exclusion_filter(self) -> Callable[[Path], bool]
62
```
63

64
Creates a filter function for excluding files and directories from analysis.
65

66
**Returns:**
67
- `Callable[[Path], bool]` - Filter function that returns True if path should be excluded
68

69
The filter checks against:
70
- Ignore patterns from configuration and profiles
71
- Ignore paths from configuration and profiles  
72
- Library-specific ignore patterns (e.g., Django migrations)
73

74
### Output Configuration
75

76
```python { .api }
77
def get_output_report(self) -> list[tuple[str, list[str]]]
78
```
79

80
Gets the configured output format and target files.
81

82
**Returns:**
83
- `list[tuple[str, list[str]]]` - List of (format_name, target_files) tuples
84

85
Defaults to `("grouped", [])` if no specific format is configured.
86

87
```python { .api }
88
def get_summary_information(self) -> dict[str, Any]
89
```
90

91
Gets summary information about the configuration for reporting.
92

93
**Returns:**
94
- `dict[str, Any]` - Dictionary containing:
95
  - `libraries`: list[str] - Detected libraries
96
  - `strictness`: Optional[str] - Strictness level
97
  - `profiles`: str - Comma-separated profile names
98
  - `tools`: list[str] - Tools to be run
99

100
### Tool Configuration Access
101

102
```python { .api }
103
def get_disabled_messages(self, tool_name: str) -> list[str]
104
```
105

106
Gets list of message codes disabled for a specific tool.
107

108
**Parameters:**
109
- `tool_name`: str - Name of the tool
110

111
**Returns:**
112
- `list[str]` - List of disabled message codes
113

114
```python { .api }
115
def get_enabled_messages(self, tool_name: str) -> list[str]
116
```
117

118
Gets list of message codes enabled for a specific tool.
119

120
**Parameters:**
121
- `tool_name`: str - Name of the tool
122

123
**Returns:**
124
- `list[str]` - List of enabled message codes
125

126
```python { .api }
127
def tool_options(self, tool_name: str) -> dict[str, Any]
128
```
129

130
Gets tool-specific configuration options.
131

132
**Parameters:**
133
- `tool_name`: str - Name of the tool
134

135
**Returns:**
136
- `dict[str, Any]` - Tool-specific options dictionary
137

138
```python { .api }
139
def external_config_location(self, tool_name: str) -> Optional[Path]
140
```
141

142
Gets the path to external configuration file for a tool.
143

144
**Parameters:**
145
- `tool_name`: str - Name of the tool
146

147
**Returns:**
148
- `Optional[Path]` - Path to external config file, or None if not configured
149

150
```python { .api }
151
def use_external_config(self, _: Any) -> bool
152
```
153

154
Determines whether to use external configuration files for tools.
155

156
**Returns:**
157
- `bool` - True if external config should be used
158

159
### Exit Behavior
160

161
```python { .api }
162
def exit_with_zero_on_success(self) -> bool
163
```
164

165
Determines whether to exit with code 0 even when issues are found.
166

167
**Returns:**
168
- `bool` - True if --zero-exit flag was provided
169

170
### Configuration Properties
171

172
The ProspectorConfig class provides numerous boolean and scalar properties for accessing configuration settings:
173

174
```python { .api }
175
@property
176
def die_on_tool_error(self) -> bool
177
```
178

179
Whether to exit immediately if a tool encounters an error.
180

181
```python { .api }
182
@property
183
def summary_only(self) -> bool
184
```
185

186
Whether to output only summary information.
187

188
```python { .api }
189
@property
190
def messages_only(self) -> bool
191
```
192

193
Whether to output only messages (no summary).
194

195
```python { .api }
196
@property
197
def quiet(self) -> bool
198
```
199

200
Whether to suppress normal output.
201

202
```python { .api }
203
@property
204
def blending(self) -> bool
205
```
206

207
Whether to blend/deduplicate similar messages from different tools.
208

209
```python { .api }
210
@property
211
def absolute_paths(self) -> bool
212
```
213

214
Whether to use absolute paths in output.
215

216
```python { .api }
217
@property
218
def max_line_length(self) -> int
219
```
220

221
Maximum line length setting for tools that support it.
222

223
```python { .api }
224
@property
225
def include_tool_stdout(self) -> bool
226
```
227

228
Whether to include tool stdout/stderr in messages.
229

230
```python { .api }
231
@property
232
def direct_tool_stdout(self) -> bool
233
```
234

235
Whether to pass tool output directly to console.
236

237
```python { .api }
238
@property
239
def show_profile(self) -> bool
240
```
241

242
Whether to include profile information in output.
243

244
```python { .api }
245
@property
246
def legacy_tool_names(self) -> bool
247
```
248

249
Whether to use legacy tool names in output.
250

251
## Usage Examples
252

253
### Basic Configuration
254

255
```python
256
from prospector.config import ProspectorConfig
257
from pathlib import Path
258

259
# Default configuration using current directory
260
config = ProspectorConfig()
261

262
# Configuration with specific working directory
263
config = ProspectorConfig(workdir=Path("/path/to/project"))
264

265
# Access configuration properties
266
print(f"Tools to run: {config.tools_to_run}")
267
print(f"Libraries detected: {config.libraries}")
268
print(f"Blending enabled: {config.blending}")
269
```
270

271
### Working with Tools
272

273
```python
274
from prospector.config import ProspectorConfig
275
from prospector.finder import FileFinder
276
from pathlib import Path
277

278
config = ProspectorConfig()
279

280
# Discover files
281
paths = [Path(".")]
282
found_files = FileFinder(*paths, exclusion_filters=[config.make_exclusion_filter()])
283

284
# Get configured tools
285
tools = config.get_tools(found_files)
286

287
# Check how tools were configured
288
for tool_name, config_source in config.configured_by.items():
289
    if config_source:
290
        print(f"{tool_name} configured from: {config_source}")
291
    else:
292
        print(f"{tool_name} using default configuration")
293
```
294

295
### Tool-Specific Configuration
296

297
```python
298
from prospector.config import ProspectorConfig
299

300
config = ProspectorConfig()
301

302
# Get tool options
303
pylint_options = config.tool_options("pylint")
304
print(f"Pylint options: {pylint_options}")
305

306
# Check disabled messages
307
disabled = config.get_disabled_messages("pylint")
308
print(f"Disabled pylint messages: {disabled}")
309

310
# Check if external config should be used
311
if config.use_external_config("pylint"):
312
    external_config = config.external_config_location("pylint")
313
    if external_config:
314
        print(f"Using external pylint config: {external_config}")
315
```
316

317
### File Filtering
318

319
```python
320
from prospector.config import ProspectorConfig
321
from pathlib import Path
322

323
config = ProspectorConfig()
324

325
# Create exclusion filter
326
exclusion_filter = config.make_exclusion_filter()
327

328
# Test paths
329
test_paths = [
330
    Path("src/main.py"),
331
    Path("migrations/0001_initial.py"),
332
    Path("__pycache__/cache.py"),
333
    Path(".git/config")
334
]
335

336
for path in test_paths:
337
    if exclusion_filter(path):
338
        print(f"Excluding: {path}")
339
    else:
340
        print(f"Including: {path}")
341
```