0
# Configuration Management
1

2
Configuration handling for command-line arguments and configuration files, supporting multiple configuration sources including pyproject.toml, setup.cfg, and tox.ini files.
3

4
## Capabilities
5

6
### Configurater Class
7

8
The main configuration management class that handles command-line argument parsing and configuration file reading.
9

10
```python { .api }
11
class Configurater:
12
    """Read and store all docformatter configuration information."""
13
    
14
    # Class attributes
15
    parser: argparse.ArgumentParser  # Argument parser instance
16
    flargs_dct: Dict[str, Union[bool, float, int, str]]  # Configuration file arguments
17
    configuration_file_lst: List[str]  # Supported configuration files
18
    args: argparse.Namespace  # Parsed arguments
19
    
20
    def __init__(self, args: List[Union[bool, int, str]]) -> None:
21
        """
22
        Initialize configuration manager.
23
        
24
        Args:
25
            args: List of command-line arguments to parse
26
        """
27
    
28
    def do_parse_arguments(self) -> None:
29
        """
30
        Parse command-line arguments and read configuration files.
31
        
32
        Combines arguments from command-line and configuration files,
33
        with command-line arguments taking precedence.
34
        """
35
```
36

37
#### Configuration File Support
38

39
```python { .api }
40
# Supported configuration files (in order of precedence)
41
configuration_file_lst = [
42
    "pyproject.toml",    # Primary configuration file (TOML format)
43
    "setup.cfg",         # Legacy setuptools configuration
44
    "tox.ini",          # Tox configuration file
45
]
46
```
47

48
#### Internal Configuration Methods
49

50
```python { .api }
51
def _do_read_configuration_file(self) -> None:
52
    """
53
    Read configuration from supported configuration files.
54
    
55
    Searches for configuration files in current directory and reads
56
    docformatter section from the first found file.
57
    """
58

59
def _do_read_toml_configuration(self) -> None:
60
    """
61
    Read TOML configuration from pyproject.toml.
62
    
63
    Uses tomllib (Python >=3.11) or tomli (Python <3.11) to parse
64
    [tool.docformatter] section.
65
    """
66

67
def _do_read_parser_configuration(self) -> None:
68
    """
69
    Read parser-style configuration from setup.cfg or tox.ini.
70
    
71
    Parses [docformatter] section using ConfigParser.
72
    """
73
```
74

75
## Command-Line Arguments
76

77
### File Processing Options
78

79
```python { .api }
80
# File input/output control
81
--in-place, -i          # Modify files in place instead of printing diffs
82
--check, -c             # Only check formatting, don't modify files
83
--diff, -d              # Show diffs when used with --check or --in-place
84
--recursive, -r         # Process directories recursively
85
--exclude PATTERNS      # Exclude files/directories by name patterns
86
files                   # Files to format or '-' for standard input
87
```
88

89
### Format Control Options
90

91
```python { .api }
92
# Docstring formatting control
93
--black                     # Black formatter compatibility mode
94
--wrap-summaries LENGTH     # Wrap summary lines at LENGTH (default: 79, 88 with --black)
95
--wrap-descriptions LENGTH  # Wrap description lines at LENGTH (default: 72, 88 with --black)
96
--force-wrap               # Force wrapping even if messy
97
--tab-width WIDTH          # Tab width for indentation (default: 1)
98
--make-summary-multi-line  # Convert single-line to multi-line docstrings
99
--close-quotes-on-newline  # Place closing quotes on new line when wrapping
100
```
101

102
### Content Control Options
103

104
```python { .api }
105
# Docstring content control
106
--blank                    # Add blank line after description
107
--pre-summary-newline     # Add newline before summary in multi-line docstrings
108
--pre-summary-space       # Add space after opening triple quotes
109
--non-cap WORDS           # Words not to capitalize when first in summary
110
--style STYLE             # Docstring style: 'sphinx' (default) or 'epytext'
111
--non-strict              # Don't strictly follow reST syntax for lists
112
```
113

114
### Processing Control Options
115

116
```python { .api }
117
# Processing range and filtering
118
--range START END              # Process docstrings between line numbers
119
--docstring-length MIN MAX     # Process docstrings within length range
120
--rest-section-adorns REGEX    # Regex for reST section adornments
121
--config CONFIG               # Path to configuration file
122
```
123

124
### Information Options
125

126
```python { .api }
127
--help, -h     # Show help message
128
--version      # Show version number
129
```
130

131
## Configuration Files
132

133
### pyproject.toml Configuration
134

135
```toml
136
[tool.docformatter]
137
black = true
138
wrap-summaries = 88
139
wrap-descriptions = 88
140
make-summary-multi-line = false
141
close-quotes-on-newline = false
142
force-wrap = false
143
tab-width = 4
144
blank = false
145
pre-summary-newline = false
146
pre-summary-space = false
147
non-strict = false
148
style = "sphinx"
149
non-cap = ["docformatter", "API"]
150
exclude = ["tests/", "build/"]
151
```
152

153
### setup.cfg Configuration
154

155
```ini
156
[docformatter]
157
black = True
158
wrap-summaries = 88
159
wrap-descriptions = 88
160
make-summary-multi-line = False
161
force-wrap = False
162
tab-width = 4
163
blank = False
164
pre-summary-newline = False
165
pre-summary-space = False
166
non-strict = False
167
style = sphinx
168
non-cap = docformatter,API
169
exclude = tests/,build/
170
```
171

172
### tox.ini Configuration
173

174
```ini
175
[docformatter]
176
black = True
177
wrap-summaries = 88
178
wrap-descriptions = 88
179
make-summary-multi-line = False
180
force-wrap = False
181
tab-width = 4
182
blank = False
183
pre-summary-newline = False
184
pre-summary-space = False
185
non-strict = False
186
style = sphinx
187
non-cap = docformatter,API
188
exclude = tests/,build/
189
```
190

191
## Usage Examples
192

193
### Basic Configuration Setup
194

195
```python
196
from docformatter import Configurater
197

198
# Simple file formatting
199
args = ['--in-place', 'example.py']
200
configurator = Configurater(args)
201
configurator.do_parse_arguments()
202

203
# Access parsed arguments
204
print(f"In-place mode: {configurator.args.in_place}")
205
print(f"Files to format: {configurator.args.files}")
206
```
207

208
### Configuration with Multiple Options
209

210
```python
211
from docformatter import Configurater
212

213
# Complex configuration
214
args = [
215
    '--black',
216
    '--recursive',
217
    '--wrap-summaries', '88',
218
    '--wrap-descriptions', '88',
219
    '--exclude', 'tests/', 'build/',
220
    '--non-cap', 'API', 'JSON',
221
    '--in-place',
222
    'src/'
223
]
224

225
configurator = Configurater(args)
226
configurator.do_parse_arguments()
227

228
# Check configuration values
229
print(f"Black mode: {configurator.args.black}")
230
print(f"Summary wrap: {configurator.args.wrap_summaries}")
231
print(f"Excluded patterns: {configurator.args.exclude}")
232
print(f"Non-capitalized words: {configurator.args.non_cap}")
233
```
234

235
### Configuration File Integration
236

237
```python
238
import os
239
from docformatter import Configurater
240

241
# Change to directory with pyproject.toml
242
os.chdir('project_root')
243

244
# Configuration will be read from pyproject.toml
245
args = ['--in-place', 'src/']
246
configurator = Configurater(args)
247
configurator.do_parse_arguments()
248

249
# Configuration combines file settings with command-line args
250
# Command-line arguments override file settings
251
```
252

253
### Check Mode Configuration
254

255
```python
256
from docformatter import Configurater
257

258
# CI/CD check configuration
259
args = [
260
    '--check',
261
    '--diff',
262
    '--recursive',
263
    '.'
264
]
265

266
configurator = Configurater(args)
267
configurator.do_parse_arguments()
268

269
# Verify check mode settings
270
assert configurator.args.check is True
271
assert configurator.args.diff is True
272
assert configurator.args.in_place is False
273
```
274

275
## Configuration Precedence
276

277
Configuration values are resolved in the following order (highest to lowest precedence):
278

279
1. **Command-line arguments** - Direct CLI arguments
280
2. **Configuration file** - First found configuration file
281
3. **Default values** - Built-in default values
282

283
### Example Configuration Resolution
284

285
```python
286
# If pyproject.toml contains:
287
# [tool.docformatter]
288
# wrap-summaries = 72
289
# black = false
290

291
# And command-line is:
292
args = ['--black', '--wrap-descriptions', '88', 'file.py']
293

294
# Final configuration will be:
295
# wrap-summaries = 72    (from config file)
296
# wrap-descriptions = 88 (from command-line)
297
# black = True           (from command-line, overrides file)
298
```
299

300
## Error Handling
301

302
The Configurater handles various configuration errors:
303

304
- **Invalid Arguments**: Clear error messages for unknown options
305
- **File Not Found**: Graceful handling when specified config file doesn't exist
306
- **Parse Errors**: Detailed error messages for malformed configuration files
307
- **Type Conversion**: Automatic conversion of string values to appropriate types
308
- **Validation**: Range checking for numeric parameters
309

310
## Configuration Validation
311

312
```python
313
from docformatter import Configurater
314

315
# Invalid wrap length
316
args = ['--wrap-summaries', '-1', 'file.py']
317
try:
318
    configurator = Configurater(args)
319
    configurator.do_parse_arguments()
320
except SystemExit:
321
    print("Invalid wrap length detected")
322

323
# Missing required file argument
324
args = ['--in-place']
325
try:
326
    configurator = Configurater(args)
327
    configurator.do_parse_arguments()
328
except SystemExit:
329
    print("Missing file argument")
330
```