0
# Pydoclint
1

2
A high-performance Python docstring linter that validates docstring sections (arguments, returns, raises, yields) against function signatures and implementations. Pydoclint supports three major docstring styles (NumPy, Google, and Sphinx) and can run thousands of times faster than similar tools like darglint, making it suitable for large codebases.
3

4
## Package Information
5

6
- **Package Name**: pydoclint
7
- **Language**: Python
8
- **Installation**: `pip install pydoclint`
9
- **Flake8 Plugin**: `pip install pydoclint[flake8]`
10

11
## Core Imports
12

13
```python
14
import pydoclint
15
```
16

17
For programmatic usage:
18

19
```python
20
# Main entry points
21
from pydoclint.main import main, _checkFile, _checkPaths
22
from pydoclint.visitor import Visitor
23
from pydoclint.utils.violation import Violation
24

25
# Utility classes for argument and docstring handling
26
from pydoclint.utils.arg import Arg, ArgList
27
from pydoclint.utils.doc import Doc
28
from pydoclint.utils.parse_docstring import parseDocstring
29

30
# AST analysis utilities
31
from pydoclint.utils.return_yield_raise import (
32
    hasReturnAnnotation, hasYieldStatements, hasRaiseStatements
33
)
34
from pydoclint.utils.generic import collectFuncArgs, getDocstring
35

36
# Package version
37
import pydoclint
38
print(pydoclint.__version__)
39
```
40

41
For flake8 integration (automatic):
42

43
```python
44
# The plugin is automatically available after installation
45
# No explicit import needed - use via flake8 command line
46
```
47

48
## Basic Usage
49

50
### Command Line Usage
51

52
```python
53
# Check a single Python file
54
pydoclint myfile.py
55

56
# Check multiple files with specific style
57
pydoclint --style=google src/*.py
58

59
# Check with custom configuration
60
pydoclint --config=pyproject.toml --exclude="tests/" src/
61

62
# Generate baseline for gradual adoption
63
pydoclint --generate-baseline --baseline=violations.txt src/
64
pydoclint --baseline=violations.txt src/  # Only report new violations
65
```
66

67
### Flake8 Integration
68

69
```bash
70
# Use as flake8 plugin (DOC error codes)
71
flake8 --select=DOC src/
72

73
# Configure in setup.cfg or pyproject.toml
74
[flake8]
75
select = DOC
76
style = numpy
77
```
78

79
### Programmatic Usage
80

81
```python
82
from pathlib import Path
83
from pydoclint.main import _checkFile
84
from pydoclint.visitor import Visitor
85
import ast
86

87
# Check a single file
88
violations = _checkFile(
89
    Path("myfile.py"),
90
    style="numpy",
91
    checkArgOrder=True,
92
    checkReturnTypes=True
93
)
94

95
# Use visitor directly for custom analysis
96
with open("myfile.py") as f:
97
    source = f.read()
98
    
99
tree = ast.parse(source)
100
visitor = Visitor(style="google", checkClassAttributes=True)
101
visitor.visit(tree)
102
violations = visitor.violations
103

104
# Process violations
105
for violation in violations:
106
    print(f"Line {violation.line}: {violation.fullErrorCode} - {violation.msg}")
107
```
108

109
## Architecture
110

111
Pydoclint's architecture is built around several key components:
112

113
- **CLI Interface**: Command-line entry point with extensive configuration options
114
- **Flake8 Plugin**: Integration with flake8 linting framework via DOC error codes
115
- **AST Visitor**: Core analysis engine that traverses Python AST to validate docstrings
116
- **Docstring Parsers**: Support for NumPy, Google, and Sphinx docstring formats
117
- **Violation System**: Comprehensive error reporting with specific violation codes (DOC0xx-DOC6xx)
118
- **Configuration System**: TOML-based configuration with command-line override support
119
- **Baseline Management**: Support for gradual adoption in legacy codebases
120

121
## Capabilities
122

123
### Command Line Interface
124

125
Complete command-line tool for docstring linting with extensive configuration options, style detection, and baseline management for gradual adoption in large codebases.
126

127
```python { .api }
128
def main(
129
    ctx: click.Context,
130
    quiet: bool,
131
    exclude: str,
132
    style: str,
133
    paths: tuple[str, ...],
134
    # ... extensive configuration parameters
135
) -> None: ...
136

137
def validateStyleValue(
138
    context: click.Context,
139
    param: click.Parameter,
140
    value: str | None,
141
) -> str | None: ...
142
```
143

144
[Command Line Interface](./cli.md)
145

146
### Flake8 Plugin Integration
147

148
Seamless integration with flake8 linting workflow, providing docstring validation as part of standard Python code quality checks with DOC error codes.
149

150
```python { .api }
151
class Plugin:
152
    name: str
153
    version: str
154
    
155
    def __init__(self, tree: ast.AST) -> None: ...
156
    
157
    @classmethod
158
    def add_options(cls, parser: Any) -> None: ...
159
    
160
    @classmethod
161
    def parse_options(cls, options: Any) -> None: ...
162
    
163
    def run(self) -> Generator[tuple[int, int, str, Any], None, None]: ...
164
```
165

166
[Flake8 Plugin](./flake8-plugin.md)
167

168
### Core Visitor and Analysis
169

170
AST-based analysis engine that traverses Python code to validate docstring compliance against function signatures, with support for all docstring styles and comprehensive validation rules.
171

172
```python { .api }
173
class Visitor(ast.NodeVisitor):
174
    def __init__(
175
        self,
176
        style: str = 'numpy',
177
        argTypeHintsInSignature: bool = True,
178
        argTypeHintsInDocstring: bool = True,
179
        checkArgOrder: bool = True,
180
        checkReturnTypes: bool = True,
181
        checkYieldTypes: bool = True,
182
        checkClassAttributes: bool = True,
183
        # ... many more configuration options
184
    ) -> None: ...
185
    
186
    def visit(self, node: ast.AST) -> None: ...
187
    
188
    @property
189
    def violations(self) -> list[Violation]: ...
190
```
191

192
[Core Analysis](./core-analysis.md)
193

194
### Configuration Management
195

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

198
```python { .api }
199
def injectDefaultOptionsFromUserSpecifiedTomlFilePath(
200
    ctx: click.Context,
201
    param: click.Parameter,
202
    value: str | None,
203
) -> str | None: ...
204

205
def parseToml(paths: Sequence[str] | None) -> dict[str, Any]: ...
206

207
def parseOneTomlFile(tomlFilename: Path) -> dict[str, Any]: ...
208
```
209

210
[Configuration](./configuration.md)
211

212
### Baseline Management
213

214
Support for baseline files that enable gradual adoption of pydoclint in large codebases by tracking existing violations and only reporting new ones.
215

216
```python { .api }
217
def generateBaseline(
218
    violationsAllFiles: dict[str, list[Violation]] | dict[str, list[str]],
219
    path: Path,
220
) -> None: ...
221

222
def parseBaseline(path: Path) -> dict[str, list[str]]: ...
223

224
def reEvaluateBaseline(
225
    baseline: dict[str, list[str]],
226
    actualViolationsInAllFiles: dict[str, list[Violation]],
227
) -> tuple[bool, dict[str, list[str]], dict[str, list[Violation]]]: ...
228
```
229

230
[Baseline Management](./baseline.md)
231

232
### Violation System
233

234
Comprehensive violation reporting system with specific error codes (DOC0xx-DOC6xx) covering all categories of docstring issues, from formatting to argument mismatches.
235

236
```python { .api }
237
class Violation:
238
    code: int
239
    line: int
240
    msg: str
241
    msgPostfix: str
242
    
243
    def __init__(
244
        self,
245
        code: int,
246
        line: int = 0,
247
        msgPrefix: str = '',
248
        msgPostfix: str = '',
249
    ) -> None: ...
250
    
251
    @property
252
    def fullErrorCode(self) -> str: ...
253
    
254
    def getInfoForFlake8(self) -> tuple[int, int, str]: ...
255

256
VIOLATION_CODES: dict[int, str]
257
```
258

259
[Violation System](./violations.md)
260

261
### Utility APIs
262

263
Comprehensive utility classes and functions for programmatic docstring analysis, including argument handling, AST processing, and docstring parsing.
264

265
```python { .api }
266
class Arg:
267
    name: str
268
    typeHint: str
269
    
270
    def __init__(self, name: str, typeHint: str) -> None: ...
271
    def nameEquals(self, other: 'Arg') -> bool: ...
272
    def hasTypeHint(self) -> bool: ...
273
    def isStarArg(self) -> bool: ...
274
    
275
    @classmethod
276
    def fromDocstringParam(cls, param: DocstringParam) -> 'Arg': ...
277
    @classmethod
278
    def fromAstArg(cls, astArg: ast.arg) -> 'Arg': ...
279

280
class ArgList:
281
    infoList: list[Arg]
282
    
283
    def __init__(self, infoList: list[Arg]) -> None: ...
284
    def length(self) -> int: ...
285
    def equals(self, other: 'ArgList') -> bool: ...
286
    def subtract(self, other: 'ArgList') -> 'ArgList': ...
287
    
288
class Doc:
289
    def __init__(self, docstring: str, style: str = 'numpy') -> None: ...
290
    
291
    @property
292
    def isShortDocstring(self) -> bool: ...
293
    @property
294
    def argList(self) -> ArgList: ...
295
    @property
296
    def hasReturnsSection(self) -> bool: ...
297
    @property
298
    def hasYieldsSection(self) -> bool: ...
299

300
# AST analysis functions
301
def hasReturnAnnotation(node: FuncOrAsyncFuncDef) -> bool: ...
302
def hasYieldStatements(node: FuncOrAsyncFuncDef) -> bool: ...
303
def hasRaiseStatements(node: FuncOrAsyncFuncDef) -> bool: ...
304
def collectFuncArgs(node: FuncOrAsyncFuncDef) -> list[ast.arg]: ...
305
def parseDocstring(docstring: str, style: str) -> Doc | None: ...
306
```
307

308
[Utility APIs](./utility-apis.md)
309

310
## Package Information
311

312
```python { .api }
313
# Package metadata
314
__version__: str  # Package version string from metadata
315
```
316

317
## Entry Points
318

319
```python { .api }
320
# CLI entry point (installed as 'pydoclint' command)
321
# Defined in pyproject.toml: pydoclint = "pydoclint.main:main"
322

323
# Flake8 plugin entry point (DOC error codes)
324
# Defined in pyproject.toml: DOC = "pydoclint.flake8_entry:Plugin"
325
```
326

327
## Types
328

329
```python { .api }
330
# Core data types
331
class Violation:
332
    code: int
333
    line: int
334
    msg: str
335
    msgPostfix: str
336
    fullErrorCode: str
337

338
class Visitor(ast.NodeVisitor):
339
    violations: list[Violation]
340

341
# Utility data types
342
class Arg:
343
    name: str
344
    typeHint: str
345

346
class ArgList:
347
    infoList: list[Arg]
348

349
class Doc:
350
    """Parsed docstring representation"""
351
    pass
352

353
@dataclass
354
class ReturnArg:
355
    type: str
356
    description: str
357

358
@dataclass
359
class YieldArg:
360
    type: str
361
    description: str
362

363
# AST node unions
364
FuncOrAsyncFuncDef = Union[ast.FunctionDef, ast.AsyncFunctionDef]
365
ClassOrFunctionDef = Union[ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef]
366

367
# Enumerations
368
class MethodType(Enum):
369
    FUNCTION = "function"
370
    METHOD = "method"
371
    CLASSMETHOD = "classmethod"
372
    STATICMETHOD = "staticmethod"
373
    PROPERTY = "property"
374

375
# Configuration types
376
ConfigDict = dict[str, Any]
377
ViolationsDict = dict[str, list[Violation]]
378
BaselineDict = dict[str, list[str]]
379

380
# Custom exceptions
381
class EdgeCaseError(Exception):
382
    """Exception for edge cases in analysis"""
383
    pass
384

385
# External types from dependencies
386
DocstringParam = Any  # From docstring_parser_fork
387
DocstringAttr = Any   # From docstring_parser_fork
388
```