0
# Configuration Management
1

2
TOML-based configuration system with support for pyproject.toml integration and command-line overrides, enabling flexible project-specific setup.
3

4
## Capabilities
5

6
### TOML Configuration Loading
7

8
Functions for loading and parsing TOML configuration files with support for custom configuration paths and pyproject.toml integration.
9

10
```python { .api }
11
def injectDefaultOptionsFromUserSpecifiedTomlFilePath(
12
    ctx: click.Context,
13
    param: click.Parameter,
14
    value: str | None,
15
) -> str | None:
16
    """
17
    Inject default options from user-specified .toml file path.
18
    
19
    Loads configuration from a custom TOML file and injects the settings
20
    into the click context as default values for command-line options.
21
    
22
    Parameters:
23
    - ctx: Click context for command-line processing
24
    - param: Click parameter (placeholder, not used)
25
    - value: Full path to the TOML configuration file
26
    
27
    Returns:
28
    str | None: The full path of the TOML file, or None if not provided
29
    """
30

31
def parseToml(paths: Sequence[str] | None) -> dict[str, Any]:
32
    """
33
    Parse the pyproject.toml located in the common parent of paths.
34
    
35
    Finds and parses pyproject.toml configuration in the common parent
36
    directory of the provided paths, extracting pydoclint configuration.
37
    
38
    Parameters:
39
    - paths: Sequence of file/directory paths to determine common parent
40
    
41
    Returns:
42
    dict[str, Any]: Parsed configuration dictionary
43
    """
44

45
def parseOneTomlFile(tomlFilename: Path) -> dict[str, Any]:
46
    """
47
    Parse a single TOML configuration file.
48
    
49
    Reads and parses a TOML file, extracting pydoclint-specific configuration
50
    from the [tool.pydoclint] section.
51
    
52
    Parameters:
53
    - tomlFilename: Path to TOML file to parse
54
    
55
    Returns:
56
    dict[str, Any]: Configuration dictionary with pydoclint settings
57
    
58
    Raises:
59
    FileNotFoundError: If TOML file doesn't exist
60
    tomllib.TOMLDecodeError: If TOML file is malformed
61
    """
62

63
def updateCtxDefaultMap(ctx: click.Context, config: dict[str, Any]) -> None:
64
    """
65
    Update click context default map with configuration values.
66
    
67
    Merges configuration values into the click context's default map,
68
    allowing TOML configuration to serve as defaults for command-line options.
69
    
70
    Parameters:
71
    - ctx: Click context to update
72
    - config: Configuration dictionary to merge
73
    """
74
```
75

76
### Configuration Utilities
77

78
Helper functions for processing configuration paths and determining common parent directories.
79

80
```python { .api }
81
def getCommonParentOfFiles(paths: Sequence[str]) -> Path:
82
    """
83
    Get common parent directory of multiple file paths.
84
    
85
    Determines the deepest common parent directory containing all
86
    specified paths, used for locating configuration files.
87
    
88
    Parameters:
89
    - paths: Sequence of file/directory paths
90
    
91
    Returns:
92
    Path: Common parent directory path
93
    """
94

95
def locateConfigFile(
96
    startPath: Path,
97
    configFilename: str = "pyproject.toml"
98
) -> Path | None:
99
    """
100
    Locate configuration file by searching up directory tree.
101
    
102
    Searches from startPath upward through parent directories to find
103
    the specified configuration file.
104
    
105
    Parameters:
106
    - startPath: Directory to start searching from
107
    - configFilename: Name of configuration file to locate
108
    
109
    Returns:
110
    Path | None: Path to configuration file if found, None otherwise
111
    """
112
```
113

114
## Usage Examples
115

116
### pyproject.toml Configuration
117

118
```toml
119
[tool.pydoclint]
120
style = "numpy"
121
exclude = '\.git|\.tox|tests/'
122
arg-type-hints-in-signature = true
123
arg-type-hints-in-docstring = true
124
check-arg-order = true
125
skip-checking-short-docstrings = true
126
skip-checking-raises = false
127
allow-init-docstring = false
128
check-return-types = true
129
check-yield-types = true
130
ignore-underscore-args = true
131
ignore-private-args = false
132
check-class-attributes = true
133
should-document-private-class-attributes = false
134
treat-property-methods-as-class-attributes = false
135
require-return-section-when-returning-nothing = false
136
require-yield-section-when-yielding-nothing = false
137
only-attrs-with-ClassVar-are-treated-as-class-attrs = false
138
should-document-star-arguments = true
139
should-declare-assert-error-if-assert-statement-exists = false
140
check-style-mismatch = false
141
check-arg-defaults = false
142
```
143

144
### Custom Configuration File
145

146
```python
147
# Use custom configuration file
148
pydoclint --config=custom-pydoclint.toml src/
149

150
# Configuration file: custom-pydoclint.toml
151
[tool.pydoclint]
152
style = "google"
153
exclude = "tests/|migrations/|__pycache__/"
154
check-class-attributes = true
155
check-return-types = true
156
show-filenames-in-every-violation-message = true
157
```
158

159
### Programmatic Configuration Loading
160

161
```python
162
from pathlib import Path
163
from pydoclint.parse_config import parseOneTomlFile, parseToml
164

165
# Load specific configuration file
166
config_path = Path("pyproject.toml")
167
config = parseOneTomlFile(config_path)
168

169
# Auto-discover configuration from paths
170
paths = ["src/module1.py", "src/module2.py"]
171
config = parseToml(paths)
172

173
# Use configuration
174
style = config.get("style", "numpy")
175
exclude_pattern = config.get("exclude", r"\.git|\.tox")
176
check_returns = config.get("check-return-types", True)
177
```
178

179
### Configuration Precedence
180

181
Configuration values are applied in this order (later values override earlier):
182

183
1. **Built-in defaults** (e.g., style="numpy")
184
2. **pyproject.toml** or custom TOML file
185
3. **Command-line arguments** (highest precedence)
186

187
```python
188
# pyproject.toml has style = "google"
189
# Command line overrides with --style=numpy
190
pydoclint --style=numpy src/  # Uses numpy style
191

192
# TOML configuration is used for unspecified options
193
# pyproject.toml has check-return-types = true
194
pydoclint --style=numpy src/  # Uses numpy style AND check-return-types = true
195
```
196

197
### Complex Configuration Examples
198

199
```toml
200
# Production-ready configuration
201
[tool.pydoclint]
202
style = "google"
203
exclude = '''
204
    \.git|
205
    \.venv|
206
    \.tox|
207
    __pycache__|
208
    \.pytest_cache|
209
    build/|
210
    dist/|
211
    docs/_build/|
212
    tests/fixtures/|
213
    migrations/
214
'''
215
arg-type-hints-in-signature = true
216
arg-type-hints-in-docstring = true
217
check-arg-order = true
218
check-return-types = true
219
check-yield-types = true
220
check-class-attributes = true
221
ignore-underscore-args = true
222
skip-checking-short-docstrings = true
223
require-return-section-when-returning-nothing = false
224
should-document-star-arguments = true
225
```
226

227
```toml
228
# Strict configuration for new projects
229
[tool.pydoclint]
230
style = "numpy"
231
check-return-types = true
232
check-yield-types = true  
233
check-class-attributes = true
234
check-style-mismatch = true
235
require-return-section-when-returning-nothing = true
236
require-yield-section-when-yielding-nothing = true
237
should-document-star-arguments = true
238
should-declare-assert-error-if-assert-statement-exists = true
239
ignore-underscore-args = false
240
ignore-private-args = false
241
skip-checking-short-docstrings = false
242
```
243

244
```toml
245
# Legacy codebase configuration with baseline
246
[tool.pydoclint]
247
style = "sphinx"
248
exclude = "legacy/|deprecated/"
249
skip-checking-short-docstrings = true
250
skip-checking-raises = true
251
allow-init-docstring = true
252
ignore-underscore-args = true
253
ignore-private-args = true
254
baseline = "pydoclint-baseline.txt"
255
auto-regenerate-baseline = true
256
```
257

258
## Configuration Options Reference
259

260
| Option | Type | Default | Description |
261
|--------|------|---------|-------------|
262
| `style` | str | "numpy" | Docstring style (numpy/google/sphinx) |
263
| `exclude` | str | r"\.git\|\.tox" | Regex pattern for file exclusion |
264
| `arg-type-hints-in-signature` | bool | true | Require type hints in function signatures |
265
| `arg-type-hints-in-docstring` | bool | true | Require type hints in docstring arguments |
266
| `check-arg-order` | bool | true | Validate argument order consistency |
267
| `skip-checking-short-docstrings` | bool | true | Skip validation for summary-only docstrings |
268
| `skip-checking-raises` | bool | false | Skip raises section validation |
269
| `allow-init-docstring` | bool | false | Allow both __init__ and class docstrings |
270
| `check-return-types` | bool | true | Validate return type consistency |
271
| `check-yield-types` | bool | true | Validate yield type consistency |
272
| `ignore-underscore-args` | bool | true | Ignore underscore arguments (_, __) |
273
| `ignore-private-args` | bool | false | Ignore private arguments (leading _) |
274
| `check-class-attributes` | bool | true | Validate class attributes |
275
| `baseline` | str | None | Path to baseline file |
276
| `auto-regenerate-baseline` | bool | true | Auto-update baseline when violations fixed |