0
# Error Checking and Validation
1

2
The error checking system provides the main API for validating Python files against PEP 257 docstring standards. It includes the primary `check()` function for programmatic use and the PEP257Checker class for detailed source code analysis.
3

4
## Capabilities
5

6
### Primary Check Function
7

8
The main entry point for checking files against PEP 257 compliance. Returns a generator of error objects for violations found in the specified files.
9

10
```python { .api }
11
def check(filenames, select=None, ignore=None):
12
    """
13
    Generate PEP 257 errors that exist in filenames iterable.
14
    
15
    Parameters:
16
    - filenames: iterable of str, file paths to check
17
    - select: list of str, error codes to check for (mutually exclusive with ignore)
18
    - ignore: list of str, error codes to ignore (mutually exclusive with select)
19
    
20
    Returns:
21
    generator: Error objects for each violation found
22
    
23
    Raises:
24
    IllegalConfiguration: if both select and ignore are provided
25
    """
26
```
27

28
Usage examples:
29

30
```python
31
import pep257
32

33
# Check single file
34
errors = list(pep257.check(['my_module.py']))
35

36
# Check multiple files  
37
errors = list(pep257.check(['module1.py', 'module2.py']))
38

39
# Check with specific error codes
40
errors = list(pep257.check(['my_module.py'], select=['D100', 'D101', 'D102']))
41

42
# Check while ignoring specific errors
43
errors = list(pep257.check(['my_module.py'], ignore=['D203', 'D213']))
44
```
45

46
### Source Code Checker
47

48
The PEP257Checker class provides detailed analysis of Python source code strings, applying all validation rules and returning comprehensive error reports.
49

50
```python { .api }
51
class PEP257Checker:
52
    """
53
    Checker for PEP 257 docstring compliance.
54
    
55
    Implements all error categories:
56
    - D10x: Missing docstrings
57
    - D20x: Whitespace issues  
58
    - D30x: Docstring formatting
59
    - D40x: Docstring content issues
60
    """
61
    
62
    def check_source(self, source, filename):
63
        """
64
        Check source code string for docstring violations.
65
        
66
        Parameters:
67
        - source: str, Python source code to analyze
68
        - filename: str, filename for error reporting
69
        
70
        Returns:
71
        generator: Error objects for violations found
72
        """
73
    
74
    @property
75
    def checks(self):
76
        """
77
        Get all available check methods.
78
        
79
        Returns:
80
        list: Check methods sorted by terminal priority
81
        """
82
```
83

84
Usage examples:
85

86
```python
87
from pep257 import PEP257Checker
88

89
checker = PEP257Checker()
90

91
# Check source code string
92
source_code = '''
93
def hello():
94
    print("Hello, world!")
95
'''
96

97
errors = list(checker.check_source(source_code, 'example.py'))
98
for error in errors:
99
    print(f"{error.filename}:{error.line} {error.code}: {error.message}")
100
```
101

102
### Error Objects
103

104
Error objects represent individual docstring violations with detailed context and formatting options.
105

106
```python { .api }
107
class Error:
108
    """
109
    Represents a docstring style error.
110
    
111
    Attributes:
112
    - code: str, error code (e.g., 'D100')
113
    - short_desc: str, brief error description
114
    - context: str, contextual information template
115
    - parameters: tuple, parameters for context formatting
116
    - definition: Definition, code definition where error occurred
117
    - explanation: str, detailed explanation of the error
118
    """
119
    
120
    # Class attributes for output formatting
121
    explain = False  # Show detailed explanations
122
    source = False   # Show source code context
123
    
124
    def set_context(self, definition, explanation):
125
        """
126
        Set the context for this error.
127
        
128
        Parameters:
129
        - definition: Definition, code definition object
130
        - explanation: str, detailed explanation
131
        """
132
    
133
    @property
134
    def filename(self):
135
        """str: Filename where error occurred."""
136
    
137
    @property  
138
    def line(self):
139
        """int: Line number where error occurred."""
140
    
141
    @property
142
    def message(self):
143
        """str: Formatted error message."""
144
    
145
    @property
146
    def lines(self):
147
        """str: Source code lines with line numbers."""
148
```
149

150
### Error Registry System
151

152
The error registry organizes all available error types into hierarchical groups and provides utilities for working with error codes.
153

154
```python { .api }
155
class ErrorRegistry:
156
    """Registry for all error types and error groups."""
157
    
158
    groups = []  # List of ErrorGroup instances
159
    
160
    @classmethod
161
    def create_group(cls, prefix, name):
162
        """
163
        Create a new error group.
164
        
165
        Parameters:
166
        - prefix: str, error code prefix (e.g., 'D1')
167
        - name: str, descriptive group name
168
        
169
        Returns:
170
        ErrorGroup: New error group instance
171
        """
172
    
173
    @classmethod
174
    def get_error_codes(cls):
175
        """
176
        Get all registered error codes.
177
        
178
        Returns:
179
        generator: All available error codes
180
        """
181
    
182
    @classmethod
183
    def to_rst(cls):
184
        """
185
        Generate RST table of all errors.
186
        
187
        Returns:
188
        str: Formatted RST table
189
        """
190

191
class ErrorGroup:
192
    """Represents a group of related errors."""
193
    
194
    def __init__(self, prefix, name):
195
        """
196
        Initialize error group.
197
        
198
        Parameters:
199
        - prefix: str, error code prefix
200
        - name: str, group name
201
        """
202
    
203
    def create_error(self, error_code, error_desc, error_context=None):
204
        """
205
        Create a new error type in this group.
206
        
207
        Parameters:
208
        - error_code: str, unique error code
209
        - error_desc: str, error description
210
        - error_context: str, optional context template
211
        
212
        Returns:
213
        type: New Error subclass
214
        """
215
```
216

217
### Pre-defined Error Groups
218

219
```python { .api }
220
# Missing Docstrings
221
D1xx = ErrorRegistry.create_group('D1', 'Missing Docstrings')
222
D100 = D1xx.create_error('D100', 'Missing docstring in public module')
223
D101 = D1xx.create_error('D101', 'Missing docstring in public class')
224
D102 = D1xx.create_error('D102', 'Missing docstring in public method')
225
D103 = D1xx.create_error('D103', 'Missing docstring in public function')
226
D104 = D1xx.create_error('D104', 'Missing docstring in public package')
227
D105 = D1xx.create_error('D105', 'Missing docstring in magic method')
228

229
# Whitespace Issues
230
D2xx = ErrorRegistry.create_group('D2', 'Whitespace Issues')
231

232
# Quote Issues  
233
D3xx = ErrorRegistry.create_group('D3', 'Quotes Issues')
234

235
# Content Issues
236
D4xx = ErrorRegistry.create_group('D4', 'Docstring Content Issues')
237
```
238

239
### Command Line Interface
240

241
```python { .api }
242
def main():
243
    """Main entry point for command-line interface."""
244

245
def run_pep257():
246
    """
247
    Main runner function with configuration parsing.
248
    
249
    Returns:
250
    int: Exit code (0=no violations, 1=violations, 2=invalid options)
251
    """
252
```
253

254
### Conventions
255

256
```python { .api }
257
conventions = {
258
    'pep257': set  # Set of error codes for PEP 257 convention
259
}
260
```
261

262
The pep257 convention includes all error codes except D203 (which conflicts with D211).
263

264
### Utility Functions  
265

266
```python { .api }
267
def setup_stream_handlers(conf):
268
    """
269
    Setup logging stream handlers according to configuration.
270
    
271
    Parameters:
272
    - conf: RunConfiguration, logging configuration
273
    """
274
```