0
# Flake8 Plugin Integration
1

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

4
## Capabilities
5

6
### Plugin Class
7

8
The main flake8 plugin entry point that integrates pydoclint with the flake8 linting framework.
9

10
```python { .api }
11
class Plugin:
12
    """
13
    Flake8 plugin entry point for pydoclint docstring validation.
14
    
15
    Provides seamless integration with flake8's linting workflow,
16
    adding DOC error codes for comprehensive docstring validation.
17
    """
18
    
19
    name: str  # Plugin name 'pydoclint'
20
    version: str  # Plugin version from package metadata
21
    
22
    def __init__(self, tree: ast.AST) -> None:
23
        """
24
        Initialize plugin with AST tree.
25
        
26
        Parameters:
27
        - tree: Parsed AST tree of Python source code to analyze
28
        """
29

30
    @classmethod
31
    def add_options(cls, parser: Any) -> None:
32
        """
33
        Add pydoclint-specific options to flake8 argument parser.
34
        
35
        Registers all pydoclint configuration options as flake8 command-line
36
        arguments, enabling configuration through flake8's standard mechanisms.
37
        
38
        Parameters:
39
        - parser: Flake8 argument parser to add options to
40
        
41
        Options added:
42
        - --style: Docstring style (numpy/google/sphinx)
43
        - --arg-type-hints-in-signature: Require type hints in signatures
44
        - --arg-type-hints-in-docstring: Require type hints in docstrings
45
        - --check-arg-order: Validate argument order consistency
46
        - --skip-checking-short-docstrings: Skip short summary-only docstrings
47
        - --skip-checking-raises: Skip raises section validation
48
        - --allow-init-docstring: Allow both __init__ and class docstrings
49
        - --check-return-types: Validate return type consistency
50
        - --check-yield-types: Validate yield type consistency
51
        - --ignore-underscore-args: Ignore underscore arguments
52
        - --ignore-private-args: Ignore private arguments
53
        - --check-class-attributes: Validate class attributes
54
        - --should-document-private-class-attributes: Document private class attrs
55
        - --treat-property-methods-as-class-attributes: Treat @property as class attrs
56
        - --require-return-section-when-returning-nothing: Require return for None
57
        - --require-yield-section-when-yielding-nothing: Require yields for None
58
        - --only-attrs-with-ClassVar-are-treated-as-class-attrs: ClassVar attrs only
59
        - --should-document-star-arguments: Document *args/**kwargs
60
        - --should-declare-assert-error-if-assert-statement-exists: AssertionError for asserts
61
        - --check-style-mismatch: Validate style consistency
62
        - --check-arg-defaults: Validate default values in type hints
63
        """
64

65
    @classmethod
66
    def parse_options(cls, options: Any) -> None:
67
        """
68
        Parse and store flake8 options for pydoclint configuration.
69
        
70
        Processes options provided by flake8 and stores them as class
71
        attributes for use during linting execution.
72
        
73
        Parameters:
74
        - options: Parsed options object from flake8
75
        """
76

77
    def run(self) -> Generator[tuple[int, int, str, Any], None, None]:
78
        """
79
        Run the linter and yield violation information.
80
        
81
        Executes pydoclint analysis on the provided AST tree and yields
82
        violation information in flake8's expected format.
83
        
84
        Returns:
85
        Generator yielding tuples of:
86
        - line: Line number of violation
87
        - col_offset: Column offset of violation
88
        - message: Formatted error message with DOC code
89
        - type: Plugin class type
90
        
91
        Raises:
92
        ValueError: If deprecated options are used or invalid style specified
93
        """
94
```
95

96
### Option Parsing Helper
97

98
Internal helper method for parsing boolean configuration values.
99

100
```python { .api }
101
@classmethod
102
def _bool(cls, optionName: str, optionValue: str) -> bool:
103
    """
104
    Parse string boolean values from flake8 configuration.
105
    
106
    Parameters:
107
    - optionName: Name of the option for error reporting
108
    - optionValue: String value ('True' or 'False')
109
    
110
    Returns:
111
    bool: Parsed boolean value
112
    
113
    Raises:
114
    ValueError: If optionValue is not 'True' or 'False'
115
    """
116
```
117

118
## Usage Examples
119

120
### Basic Flake8 Integration
121

122
The plugin is automatically available after installation:
123

124
```bash
125
# Install with flake8 support
126
pip install pydoclint[flake8]
127

128
# Run flake8 with pydoclint DOC codes
129
flake8 --select=DOC src/
130

131
# Combine with other linters
132
flake8 --select=E,W,F,DOC src/
133

134
# Show only pydoclint violations
135
flake8 --select=DOC src/
136
```
137

138
### Configuration in setup.cfg
139

140
```ini
141
[flake8]
142
select = DOC
143
style = numpy
144
exclude = .git,__pycache__,tests/
145
arg-type-hints-in-signature = True
146
check-class-attributes = True
147
check-return-types = True
148
```
149

150
### Configuration in pyproject.toml
151

152
```toml
153
[tool.flake8]
154
select = ["DOC"]
155
style = "google"
156
exclude = [".git", "__pycache__", "tests/"]
157
arg-type-hints-in-docstring = true
158
check-yield-types = true
159
ignore-underscore-args = true
160
```
161

162
### Advanced Usage with Multiple Tools
163

164
```bash
165
# Use with pre-commit
166
# .pre-commit-config.yaml
167
- repo: local
168
  hooks:
169
    - id: flake8-docstring
170
      name: flake8 docstring linting
171
      entry: flake8 --select=DOC
172
      language: system
173
      types: [python]
174

175
# Combine with mypy and other tools
176
flake8 --select=E,W,F,DOC --statistics src/
177
mypy src/
178
black --check src/
179
```
180

181
### Error Code Filtering
182

183
```bash
184
# Ignore specific DOC codes
185
flake8 --select=DOC --ignore=DOC101,DOC102 src/
186

187
# Focus on specific violation categories
188
flake8 --select=DOC1,DOC2 src/  # Only argument and return issues
189
flake8 --select=DOC3 src/       # Only class-related issues
190
flake8 --select=DOC4 src/       # Only yield-related issues
191
flake8 --select=DOC5 src/       # Only raises-related issues
192
```
193

194
### Per-File Exclusions
195

196
```python
197
# Use flake8 per-file ignores
198
[flake8]
199
per-file-ignores =
200
    __init__.py: DOC
201
    tests/*: DOC101,DOC102
202
    legacy/*: DOC
203
```
204

205
## Error Codes
206

207
The plugin generates DOC error codes in the following categories:
208

209
- **DOC0xx**: General and style issues (DOC001-DOC003)
210
- **DOC1xx**: Argument-related violations (DOC101-DOC111)
211
- **DOC2xx**: Return-related violations (DOC201-DOC203)
212
- **DOC3xx**: Class and __init__ violations (DOC301-DOC307)
213
- **DOC4xx**: Yield-related violations (DOC402-DOC405)
214
- **DOC5xx**: Raises-related violations (DOC501-DOC502)
215
- **DOC6xx**: Class attribute violations (DOC601-DOC603)
216

217
Each violation includes the line number, column offset, and descriptive error message following flake8 conventions.