0
# pep257
1

2
A Python static analysis tool for checking docstring conventions and style compliance with PEP 257. The tool analyzes Python source code to identify missing or improperly formatted docstrings and provides configurable checking frameworks that can be extended with custom validation rules.
3

4
## Package Information
5

6
- **Package Name**: pep257
7
- **Language**: Python
8
- **Installation**: `pip install pep257`
9
- **Python Compatibility**: 2.6, 2.7, 3.2+, PyPy
10

11
## Core Imports
12

13
```python
14
import pep257
15
```
16

17
Common usage patterns:
18

19
```python
20
from pep257 import check, PEP257Checker
21
```
22

23
## Basic Usage
24

25
```python
26
import pep257
27

28
# Check files for PEP 257 compliance
29
errors = list(pep257.check(['my_module.py']))
30
for error in errors:
31
    print(error)
32

33
# Check with specific error code selection
34
errors = list(pep257.check(['my_module.py'], select=['D100', 'D101']))
35

36
# Check while ignoring specific error codes  
37
errors = list(pep257.check(['my_module.py'], ignore=['D203']))
38
```
39

40
Command-line usage:
41

42
```bash
43
# Basic usage
44
pep257 my_module.py
45

46
# With options
47
pep257 --explain --source my_module.py
48
pep257 --select=D100,D101 my_module.py
49
pep257 --ignore=D203 my_project/
50
```
51

52
## Architecture
53

54
pep257 follows a modular architecture with distinct responsibilities:
55

56
- **Parser System**: Tokenizes and parses Python source code into an AST-like structure with Definition objects (Module, Class, Function, Method)
57
- **Error Registry**: Hierarchical error classification system with error groups (D1xx: Missing Docstrings, D2xx: Whitespace Issues, D3xx: Quote Issues, D4xx: Content Issues)  
58
- **Configuration System**: Multi-level configuration parsing supporting CLI options, config files (setup.cfg, tox.ini, .pep257), and inheritance
59
- **Checker Engine**: PEP257Checker class that applies validation rules to parsed definitions and generates error reports
60

61
## Capabilities
62

63
### Error Checking and Validation
64

65
Main API for checking Python files against PEP 257 docstring standards. Provides the primary `check()` function and PEP257Checker class for programmatic validation.
66

67
```python { .api }
68
def check(filenames, select=None, ignore=None):
69
    """Generate PEP 257 errors that exist in filenames iterable."""
70

71
class PEP257Checker:
72
    def check_source(self, source, filename):
73
        """Check source code string for docstring violations."""
74
```
75

76
[Error Checking and Validation](./error-checking.md)
77

78
### Configuration System  
79

80
Comprehensive configuration parsing system supporting CLI arguments and configuration files with inheritance. Handles error code selection, file matching patterns, and runtime options.
81

82
```python { .api }
83
class ConfigurationParser:
84
    def parse(self):
85
        """Parse configuration from CLI and files."""
86
    
87
    def get_files_to_check(self):
88
        """Generate files and error codes to check."""
89

90
class RunConfiguration:
91
    """Configuration for runtime behavior."""
92

93
class CheckConfiguration:
94
    """Configuration for error checking."""
95
```
96

97
[Configuration System](./configuration.md)
98

99
### AST Parsing and Code Analysis
100

101
Parser system that converts Python source code into structured Definition objects representing modules, classes, functions, and methods with docstring extraction.
102

103
```python { .api }
104
class Parser:
105
    def __call__(self, filelike, filename):
106
        """Parse Python source into Definition tree."""
107

108
class Definition:
109
    """Base class for all code definitions."""
110

111
class Module(Definition):
112
    """Represents a Python module."""
113

114
class Function(Definition):
115
    """Represents a function definition."""
116

117
class Class(Definition):
118
    """Represents a class definition."""
119
```
120

121
[AST Parsing and Code Analysis](./parsing.md)
122

123
## Error Categories
124

125
### D1xx: Missing Docstrings
126
- **D100**: Missing docstring in public module
127
- **D101**: Missing docstring in public class
128
- **D102**: Missing docstring in public method
129
- **D103**: Missing docstring in public function
130
- **D104**: Missing docstring in public package
131
- **D105**: Missing docstring in magic method
132

133
### D2xx: Whitespace Issues
134
- **D200-D211**: Various whitespace and formatting issues in docstrings
135

136
### D3xx: Quote Issues
137
- **D300-D302**: Docstring quote style and encoding issues
138

139
### D4xx: Content Issues
140
- **D400-D402**: Docstring content and style problems
141

142
## Constants
143

144
```python { .api }
145
__version__ = "0.7.0"
146
__all__ = ("check", "collect")  # Note: 'collect' function not implemented
147

148
# Return codes
149
NO_VIOLATIONS_RETURN_CODE = 0
150
VIOLATIONS_RETURN_CODE = 1
151
INVALID_OPTIONS_RETURN_CODE = 2
152
```
153

154
## Exceptions
155

156
```python { .api }
157
class AllError(Exception):
158
    """Exception for __all__ parsing errors."""
159

160
class IllegalConfiguration(Exception):
161
    """Exception for illegal configuration options."""
162
```