0
# Configuration Management
1

2
Configuration classes, validation functions, and output mode management for controlling darker's behavior through config files and command-line options.
3

4
## Capabilities
5

6
### Configuration Classes
7

8
Core configuration classes for managing darker settings.
9

10
```python { .api }
11
class DarkerConfig(BaseConfig, total=False):
12
    """
13
    TypedDict representing [tool.darker] configuration section.
14
    
15
    All fields are optional and have sensible defaults.
16
    """
17
    check: bool                        # Exit with error if changes needed
18
    diff: bool                         # Show diff instead of writing files
19
    flynt: bool                        # Apply flynt f-string conversion
20
    isort: bool                        # Apply isort import sorting
21
    line_length: int                   # Line length for formatting
22
    lint: list[str]                    # List of linting commands
23
    skip_magic_trailing_comma: bool    # Don't use trailing commas
24
    skip_string_normalization: bool    # Don't normalize string quotes
25
    target_version: str                # Python version target
26
    formatter: str                     # Formatter name (black, ruff, none)
27

28
class Exclusions:
29
    """
30
    File exclusion patterns for pre-processing steps.
31
    
32
    Attributes:
33
    - formatter: Set of glob patterns to exclude from formatting
34
    - isort: Set of glob patterns to exclude from import sorting
35
    - flynt: Set of glob patterns to exclude from f-string conversion
36
    """
37
    formatter: Set[str] = field(default_factory=set)
38
    isort: Set[str] = field(default_factory=set)  
39
    flynt: Set[str] = field(default_factory=set)
40
```
41

42
### Output Mode Management
43

44
Classes and functions for managing different output modes.
45

46
```python { .api }
47
class OutputMode:
48
    """Output mode constants for controlling how results are displayed."""
49
    NOTHING = "NOTHING"      # No output, just modify files
50
    DIFF = "DIFF"           # Show unified diff
51
    CONTENT = "CONTENT"     # Show reformatted content
52

53
def validate_config_output_mode(diff: bool, stdout: bool) -> OutputMode:
54
    """
55
    Validate and determine output mode from diff/stdout flags.
56
    
57
    Parameters:
58
    - diff: Whether to show diff output
59
    - stdout: Whether to output to stdout
60
    
61
    Returns:
62
    OutputMode enum value
63
    
64
    Raises:
65
    ConfigurationError: If both diff and stdout are enabled
66
    """
67
```
68

69
### Configuration Validation
70

71
Functions for validating configuration options and handling deprecated settings.
72

73
```python { .api }
74
REMOVED_CONFIG_OPTIONS: Dict[str, str]
75
"""
76
Dictionary mapping removed configuration option names to helpful error messages.
77
"""
78

79
DEPRECATED_CONFIG_OPTIONS: Set[str] 
80
"""
81
Set of configuration option names that are deprecated but still supported.
82
"""
83
```
84

85
### Target Version Configuration
86

87
Enumeration for Python version targeting.
88

89
```python { .api }
90
class TargetVersion(Enum):
91
    """
92
    Python version numbers for formatter targeting.
93
    
94
    Each enum member represents a Python version as a tuple of (major, minor).
95
    """
96
    PY33 = (3, 3)
97
    PY34 = (3, 4)
98
    PY35 = (3, 5)
99
    PY36 = (3, 6)
100
    PY37 = (3, 7)
101
    PY38 = (3, 8)
102
    PY39 = (3, 9)
103
    PY310 = (3, 10)
104
    PY311 = (3, 11)
105
    PY312 = (3, 12)
106
    PY313 = (3, 13)
107
```
108

109
## Usage Examples
110

111
### Creating Configuration
112

113
```python
114
from darker.config import DarkerConfig, OutputMode, Exclusions
115
from darker.configuration.target_version import TargetVersion
116

117
# Create configuration programmatically
118
config: DarkerConfig = {
119
    'src': ['src/', 'tests/'],
120
    'check': True,
121
    'diff': True,
122
    'isort': True,
123
    'flynt': False,
124
    'formatter': 'black',
125
    'line_length': 88,
126
    'target_version': 'py39',
127
}
128

129
# Create exclusions
130
exclusions = Exclusions(
131
    formatter={'migrations/**/*'},
132
    isort={'*/migrations/*'},
133
    flynt={'legacy_code/**/*'}
134
)
135
```
136

137
### Output Mode Validation
138

139
```python
140
from darker.config import validate_config_output_mode, OutputMode
141

142
# Valid configurations
143
mode = validate_config_output_mode(diff=True, stdout=False)
144
assert mode == OutputMode.DIFF
145

146
mode = validate_config_output_mode(diff=False, stdout=True)  
147
assert mode == OutputMode.CONTENT
148

149
mode = validate_config_output_mode(diff=False, stdout=False)
150
assert mode == OutputMode.NOTHING
151

152
# Invalid configuration - raises ConfigurationError
153
try:
154
    validate_config_output_mode(diff=True, stdout=True)
155
except ConfigurationError as e:
156
    print("Cannot use both --diff and --stdout")
157
```
158

159
### Target Version Usage
160

161
```python
162
from darker.configuration.target_version import TargetVersion
163

164
# Using target versions
165
target = TargetVersion.PY39
166
print(f"Target Python version: {target.value}")  # (3, 9)
167

168
# Convert from string
169
target_str = "py311"
170
for tv in TargetVersion:
171
    if tv.name.lower() == target_str:
172
        target = tv
173
        break
174
```
175

176
### Configuration File Examples
177

178
#### pyproject.toml Configuration
179

180
```toml
181
[tool.darker]
182
src = ["src", "tests", "scripts"]
183
revision = "origin/main..."
184
check = true
185
diff = true
186
isort = true
187
flynt = false
188
formatter = "black"
189
line_length = 88
190
target_version = "py39"
191
color = true
192

193
# Black-specific settings go in [tool.black]
194
[tool.black]
195
skip-string-normalization = true
196
target-version = ["py39", "py310", "py311"]
197

198
# isort settings go in [tool.isort]  
199
[tool.isort]
200
profile = "black"
201
multi_line_output = 3
202
```
203

204
#### Programmatic Configuration Loading
205

206
```python
207
from darker.command_line import parse_command_line
208
from darker.config import DarkerConfig
209

210
# Load configuration from files and command line
211
args = parse_command_line(["src/", "--diff"])
212

213
# Extract configuration
214
config: DarkerConfig = {
215
    'src': args.src,
216
    'revision': args.revision,
217
    'diff': args.diff,
218
    'check': args.check,
219
    'isort': args.isort,
220
    'flynt': args.flynt,
221
    'formatter': getattr(args, 'formatter', 'black'),
222
    'line_length': getattr(args, 'line_length', 88),
223
    'target_version': getattr(args, 'target_version', 'py39'),
224
}
225

226
# Use configuration
227
if config.get('diff'):
228
    output_mode = OutputMode.DIFF
229
elif config.get('stdout'):
230
    output_mode = OutputMode.CONTENT
231
else:
232
    output_mode = OutputMode.NOTHING
233
```
234

235
### Handling Deprecated Options
236

237
```python
238
from darker.config import REMOVED_CONFIG_OPTIONS, DEPRECATED_CONFIG_OPTIONS
239

240
def validate_user_config(user_config):
241
    """Validate user configuration and show helpful messages."""
242
    for option in user_config:
243
        if option in REMOVED_CONFIG_OPTIONS:
244
            error_msg = REMOVED_CONFIG_OPTIONS[option]
245
            raise ConfigurationError(f"Option '{option}' has been removed. {error_msg}")
246
        
247
        if option in DEPRECATED_CONFIG_OPTIONS:
248
            print(f"Warning: Option '{option}' is deprecated and may be removed in a future version")
249
```