0
# Command Line Interface
1
2
Command line argument parsing, configuration management, and option validation for the darker command-line tool.
3
4
## Capabilities
5
6
### Argument Parser Creation
7
8
Functions for creating and configuring the command-line argument parser.
9
10
```python { .api }
11
def make_argument_parser(require_src: bool) -> ArgumentParser:
12
"""
13
Create the argument parser object for darker command-line interface.
14
15
Parameters:
16
- require_src: True to require at least one path as positional argument
17
18
Returns:
19
Configured ArgumentParser instance with all CLI options
20
"""
21
```
22
23
### Command Line Parsing
24
25
Parse command-line arguments and merge with configuration file settings.
26
27
```python { .api }
28
def parse_command_line(
29
argv: Optional[List[str]]
30
) -> Tuple[Namespace, DarkerConfig, DarkerConfig]:
31
"""
32
Parse command line arguments with configuration file defaults.
33
34
Reads configuration from pyproject.toml [tool.darker] section,
35
then applies command-line overrides, and returns both the parsed
36
arguments and the effective configuration.
37
38
Parameters:
39
- argv: Command line arguments list (typically sys.argv[1:], None for sys.argv[1:])
40
41
Returns:
42
Tuple of:
43
- Namespace: Parsed command line arguments
44
- DarkerConfig: Effective configuration combining defaults, file, and CLI
45
- DarkerConfig: Configuration options that differ from defaults
46
"""
47
```
48
49
### Configuration Validation
50
51
Functions for validating and processing configuration options.
52
53
```python { .api }
54
def show_config_deprecations(config: DarkerConfig) -> None:
55
"""
56
Display deprecation warnings for outdated configuration options.
57
58
Parameters:
59
- config: Configuration dictionary to validate
60
"""
61
```
62
63
## Command Line Options
64
65
### Core Options
66
67
```bash
68
# Source paths
69
darker [paths...] # Files/directories to process
70
71
# Revision control
72
--revision REV # Git revision to compare against
73
-r REV # Short form of --revision
74
75
# Output modes
76
--diff # Show diff instead of writing files
77
--stdout # Output to stdout instead of files
78
-d # Short form of --stdout
79
--check # Exit with error if changes needed
80
81
# Formatting options
82
--isort # Apply isort import sorting
83
-i # Short form of --isort
84
--flynt # Apply flynt f-string conversion
85
-f # Short form of --flynt
86
87
# Formatter selection
88
--formatter NAME # Choose formatter (black, ruff, none)
89
90
# Configuration
91
--config PATH # Path to configuration file
92
-c PATH # Short form of --config
93
94
# Output formatting
95
--color # Use colored output
96
--no-color # Disable colored output
97
98
# Verbosity
99
--verbose # Increase logging verbosity
100
-v # Short form of --verbose
101
--quiet # Decrease logging verbosity
102
-q # Short form of --quiet
103
104
# Black compatibility options
105
--line-length LENGTH # Line length for formatting
106
-l LENGTH # Short form of --line-length
107
--target-version VER # Python version target
108
--skip-string-normalization # Don't normalize string quotes
109
--skip-magic-trailing-comma # Don't use trailing commas
110
--preview # Enable preview style features
111
```
112
113
## Usage Examples
114
115
### Basic Command Line Usage
116
117
```python
118
from darker.command_line import parse_command_line
119
120
# Parse minimal arguments
121
args = parse_command_line(["src/", "--diff", "--check"])
122
print(f"Paths: {args.src}")
123
print(f"Show diff: {args.diff}")
124
print(f"Check mode: {args.check}")
125
126
# Parse with formatting options
127
args = parse_command_line([
128
"mymodule.py",
129
"--isort",
130
"--flynt",
131
"--formatter", "black",
132
"--line-length", "88",
133
"--color"
134
])
135
```
136
137
### Custom Configuration
138
139
```python
140
from darker.command_line import parse_command_line
141
142
# Using custom config file
143
args = parse_command_line([
144
"src/",
145
"--config", "my-darker.toml",
146
"--revision", "HEAD~2"
147
], config_filenames=["my-darker.toml", "pyproject.toml"])
148
149
# Access parsed configuration
150
formatter_name = getattr(args, 'formatter', 'black')
151
use_isort = args.isort
152
line_length = getattr(args, 'line_length', 88)
153
```
154
155
### Parser Configuration
156
157
```python
158
from darker.command_line import make_argument_parser
159
160
# Create parser that requires source paths
161
parser = make_argument_parser(require_src=True)
162
args = parser.parse_args(["src/module.py", "--diff"])
163
164
# Create parser that allows no source paths (for piped input)
165
parser = make_argument_parser(require_src=False)
166
args = parser.parse_args(["--stdin-filename", "module.py"])
167
```
168
169
## Configuration File Integration
170
171
### pyproject.toml Configuration
172
173
```toml
174
[tool.darker]
175
src = ["src", "tests"]
176
revision = "origin/main..."
177
diff = true
178
check = false
179
isort = true
180
flynt = false
181
formatter = "black"
182
line_length = 88
183
target_version = "py39"
184
color = true
185
```
186
187
### Accessing Configuration in Code
188
189
```python
190
from darker.command_line import parse_command_line
191
from darker.config import DarkerConfig
192
193
# Parse with config file integration
194
args = parse_command_line(["--diff"])
195
196
# Configuration is merged into args namespace
197
config: DarkerConfig = {
198
'src': args.src,
199
'diff': args.diff,
200
'check': args.check,
201
'isort': args.isort,
202
'flynt': args.flynt,
203
'formatter': getattr(args, 'formatter', 'black'),
204
'line_length': getattr(args, 'line_length', 88),
205
}
206
```