0
# Configuration System
1

2
Powerful configuration system supporting CLI arguments, TOML configuration files, and path-specific amendment rules for flexible analysis customization.
3

4
## Capabilities
5

6
### Settings Class
7

8
The central configuration object that contains all analysis options and preferences.
9

10
```python { .api }
11
class Settings:
12
    """
13
    Main configuration class containing all refurb analysis options.
14
    
15
    Combines CLI arguments, configuration file settings, and defaults into a single
16
    object that controls all aspects of the analysis process.
17
    
18
    Attributes:
19
    - files: list[str] - Files and directories to analyze
20
    - explain: ErrorCode | None - Specific error code to explain (for --explain command)
21
    - ignore: set[ErrorClassifier] - Error codes/categories to ignore
22
    - load: list[str] - Additional module paths to search for checks
23
    - enable: set[ErrorClassifier] - Error codes/categories to explicitly enable
24
    - disable: set[ErrorClassifier] - Error codes/categories to explicitly disable
25
    - debug: bool - Print AST representation of analyzed files
26
    - generate: bool - Generate boilerplate for new check (gen subcommand)
27
    - help: bool - Display help information
28
    - version: bool - Display version information
29
    - quiet: bool - Suppress default explanation suggestions
30
    - enable_all: bool - Enable all available checks by default
31
    - disable_all: bool - Disable all checks by default
32
    - verbose: bool - Increase output verbosity
33
    - color: bool - Use colored output in terminal
34
    - config_file: str | None - Path to configuration file used
35
    - python_version: tuple[int, int] | None - Target Python version (e.g., (3, 11))
36
    - mypy_args: list[str] - Additional arguments to pass to mypy
37
    - format: Literal["text", "github"] | None - Output format preference
38
    - sort_by: Literal["filename", "error"] | None - Error sorting preference
39
    - timing_stats: Path | None - File to export timing statistics to
40
    """
41
    files: list[str]
42
    explain: ErrorCode | None
43
    ignore: set[ErrorClassifier]
44
    load: list[str]
45
    enable: set[ErrorClassifier]
46
    disable: set[ErrorClassifier]
47
    debug: bool
48
    generate: bool
49
    help: bool
50
    version: bool
51
    quiet: bool
52
    enable_all: bool
53
    disable_all: bool
54
    verbose: bool
55
    color: bool
56
    config_file: str | None
57
    python_version: tuple[int, int] | None
58
    mypy_args: list[str]
59
    format: Literal["text", "github"] | None
60
    sort_by: Literal["filename", "error"] | None
61
    timing_stats: Path | None
62

63
    def get_python_version(self) -> tuple[int, int]:
64
        """
65
        Get target Python version for analysis.
66
        
67
        Returns:
68
        Python version tuple, using system version if not specified
69
        """
70

71
    @staticmethod
72
    def merge(old: Settings, new: Settings) -> Settings:
73
        """
74
        Merge two Settings objects with precedence rules.
75
        
76
        Combines configuration from multiple sources, with new settings
77
        taking precedence over old ones. Handles special logic for
78
        enable_all/disable_all flags and list merging.
79
        
80
        Parameters:
81
        - old: Base settings (lower precedence)  
82
        - new: Override settings (higher precedence)
83
        
84
        Returns:
85
        Merged Settings object with combined configuration
86
        """
87
```
88

89
### Configuration Loading
90

91
Functions that parse configuration from various sources and merge them into Settings objects.
92

93
```python { .api }
94
def load_settings(args: list[str]) -> Settings:
95
    """
96
    Parse command line arguments and configuration files into Settings object.
97
    
98
    Combines configuration from multiple sources in order of precedence:
99
    1. Command line arguments (highest precedence)
100
    2. Configuration file settings
101
    3. Default values (lowest precedence)
102
    
103
    Parameters:
104
    - args: Command line arguments to parse
105
    
106
    Returns:
107
    Settings object with all configuration options resolved
108
    
109
    Raises:
110
    - ValueError: For invalid argument values or configuration conflicts
111
    """
112

113
def parse_command_line_args(args: list[str]) -> Settings:
114
    """
115
    Parse command line arguments into Settings object.
116
    
117
    Handles all CLI options including flags, repeated options, and positional arguments.
118
    
119
    Parameters:
120
    - args: Raw command line arguments
121
    
122
    Returns:
123
    Settings object with CLI configuration
124
    
125
    Raises:
126
    - ValueError: For invalid or conflicting command line options
127
    """
128

129
def parse_config_file(contents: str) -> Settings:
130
    """
131
    Parse TOML configuration file contents into Settings object.
132
    
133
    Supports all CLI options plus additional configuration features:
134
    - Amendment rules for path-specific error filtering
135
    - Complex ignore/enable patterns
136
    - Structured configuration organization
137
    
138
    Parameters:
139
    - contents: TOML file contents as string
140
    
141
    Returns:
142
    Settings object with configuration file options
143
    
144
    Raises:
145
    - ValueError: For invalid TOML syntax or configuration values
146
    """
147
```
148

149
### Configuration Parsing Utilities
150

151
Specialized functions for parsing and validating specific configuration values.
152

153
```python { .api }
154
def parse_error_classifier(value: str) -> ErrorClassifier:
155
    """
156
    Parse string representation of error code or category.
157
    
158
    Supports formats like:
159
    - "FURB105" (specific error code)
160
    - "pathlib" (error category)  
161
    - "readability" (error category)
162
    
163
    Parameters:
164
    - value: String representation to parse
165
    
166
    Returns:
167
    ErrorCode or ErrorCategory object
168
    
169
    Raises:
170
    - ValueError: For invalid format or unknown error codes/categories
171
    """
172

173
def parse_error_id(value: str) -> ErrorCode:
174
    """
175
    Parse string representation of specific error code.
176
    
177
    Parameters:
178
    - value: Error code string (e.g., "FURB105")
179
    
180
    Returns:
181
    ErrorCode object
182
    
183
    Raises:
184
    - ValueError: For invalid error code format
185
    """
186

187
def parse_python_version(value: str) -> tuple[int, int]:
188
    """
189
    Parse Python version string into tuple.
190
    
191
    Parameters:
192
    - value: Version string (e.g., "3.11", "3.10")
193
    
194
    Returns:
195
    Version tuple (e.g., (3, 11))
196
    
197
    Raises:
198
    - ValueError: For invalid version format or unsupported versions
199
    """
200
```
201

202
### Configuration File Format
203

204
Refurb supports TOML configuration files, typically in `pyproject.toml`:
205

206
```toml
207
[tool.refurb]
208
# Files to analyze (optional, usually specified as CLI args)
209
files = ["src/", "tests/"]
210

211
# Error filtering
212
ignore = ["FURB105", "readability"]
213
enable = ["FURB999"]
214
disable = ["pathlib"]
215
enable_all = false
216
disable_all = false
217

218
# Additional check modules
219
load = ["./custom_checks", "my_plugin"]
220

221
# Output formatting
222
format = "text"  # or "github"
223
sort_by = "filename"  # or "error"
224
quiet = false
225
verbose = false
226

227
# Analysis options
228
debug = false
229
python_version = "3.11"
230

231
# Amendment rules (path-specific ignores)
232
[[tool.refurb.amend]]
233
path = "legacy/"
234
ignore = ["FURB105", "FURB123"]
235

236
[[tool.refurb.amend]]
237
path = "tests/"
238
ignore = ["readability"]
239
```
240

241
### Amendment Rules
242

243
Path-specific configuration that allows different rules for different parts of the codebase:
244

245
```python
246
# Settings with amendment rules
247
settings = Settings(
248
    files=["src/"],
249
    ignore={ErrorCode(105, "FURB", "legacy/old_module.py")}
250
)
251

252
# Amendment matching logic
253
def is_ignored_via_amend(error: Error, settings: Settings) -> bool:
254
    """Check if error is ignored by path-specific amendment rules."""
255
```
256

257
### Usage Examples
258

259
```python
260
from refurb.settings import load_settings, parse_config_file
261

262
# Load from CLI args
263
settings = load_settings([
264
    "src/",
265
    "--ignore", "FURB105,readability", 
266
    "--format", "github",
267
    "--python-version", "3.11"
268
])
269

270
# Load from config file
271
toml_content = """
272
[tool.refurb]
273
ignore = ["FURB105", "readability"]
274
format = "github"
275
python_version = "3.11"
276
"""
277
file_settings = parse_config_file(toml_content)
278

279
# Combine with CLI args (CLI takes precedence)
280
combined_settings = load_settings(["src/", "--quiet"])
281

282
# Access configuration
283
print(f"Analyzing: {settings.files}")
284
print(f"Ignoring: {settings.ignore}")
285
print(f"Python version: {settings.get_python_version()}")
286
```
287

288
### Integration with Analysis
289

290
The Settings object is used throughout the analysis pipeline:
291

292
```python
293
# Error filtering uses settings
294
should_ignore = should_ignore_error(error, settings)
295

296
# Check loading respects enable/disable settings
297
checks = load_checks(settings)
298

299
# Output formatting uses display preferences
300
formatted = format_errors(errors, settings)
301

302
# Mypy integration uses Python version
303
opt.python_version = settings.get_python_version()
304
```
305

306
### Plugin Configuration
307

308
Plugin checks can define their own configuration options:
309

310
```python
311
# Custom check that respects settings
312
def check_custom_pattern(node: Node, errors: list[Error], settings: Settings) -> None:
313
    if settings.verbose:
314
        # More detailed checking in verbose mode
315
        pass
316
    
317
    # Access custom settings from config file
318
    # [tool.refurb.plugins.my_plugin]
319
    # custom_option = true
320
```