0
# Interrogate
1

2
A Python command-line tool and library for analyzing docstring coverage in Python codebases. Interrogate examines Python modules, classes, functions, and methods to identify missing docstrings and generate detailed coverage reports, helping developers maintain code documentation standards.
3

4
## Package Information
5

6
- **Package Name**: interrogate
7
- **Language**: Python
8
- **Installation**: `pip install interrogate`
9

10
Optional PNG badge support:
11
```bash
12
pip install interrogate[png]
13
```
14

15
## Core Imports
16

17
```python
18
import interrogate
19
```
20

21
For programmatic usage:
22
```python
23
from interrogate.coverage import InterrogateCoverage
24
from interrogate.config import InterrogateConfig
25
```
26

27
For CLI usage:
28
```python
29
from interrogate.cli import main
30
```
31

32
## Basic Usage
33

34
### Command Line Usage
35

36
```bash
37
# Analyze current directory
38
interrogate .
39

40
# Analyze specific files/directories
41
interrogate src/ tests/
42

43
# Generate coverage report with badge
44
interrogate --generate-badge badge.svg src/
45

46
# Fail if coverage below threshold
47
interrogate --fail-under 80 src/
48
```
49

50
### Programmatic Usage
51

52
```python
53
from interrogate.coverage import InterrogateCoverage
54
from interrogate.config import InterrogateConfig
55

56
# Create configuration
57
config = InterrogateConfig(
58
    ignore_module=True,
59
    fail_under=80,
60
)
61

62
# Run coverage analysis
63
coverage = InterrogateCoverage(["src/"], config)
64
results = coverage.get_coverage()
65

66
# Print results
67
coverage.print_results(results)
68
```
69

70
## Architecture
71

72
Interrogate is built around several key components:
73

74
- **Coverage Analysis**: Core engine that traverses Python AST to identify docstring coverage
75
- **Configuration Management**: Handles CLI options, config files (pyproject.toml, setup.cfg)
76
- **Results Processing**: Aggregates and formats coverage statistics
77
- **Badge Generation**: Creates SVG/PNG badges for documentation coverage visualization
78
- **CLI Interface**: Command-line interface built with Click framework
79

80
The analysis process uses Python's AST (Abstract Syntax Tree) to examine code structure and identify missing docstrings across modules, classes, functions, and methods.
81

82
## Capabilities
83

84
### Coverage Analysis
85

86
Core functionality for analyzing docstring coverage in Python codebases. Examines AST to identify missing docstrings and generate comprehensive coverage statistics.
87

88
```python { .api }
89
class InterrogateCoverage:
90
    def __init__(self, paths, conf=None, excluded=None, extensions=None): ...
91
    def get_coverage(self): ...
92
    def print_results(self, results, output, verbosity): ...
93

94
class InterrogateResults:
95
    total: int
96
    covered: int 
97
    missing: int
98
    perc_covered: float
99
    ret_code: int
100
    file_results: Dict[str, InterrogateFileResult]
101
```
102

103
[Coverage Analysis](./coverage-analysis.md)
104

105
### Configuration Management
106

107
Handles configuration from multiple sources including CLI arguments, pyproject.toml, and setup.cfg files. Provides unified configuration interface with validation and defaults.
108

109
```python { .api }
110
class InterrogateConfig:
111
    def __init__(self, **kwargs): ...
112

113
def find_project_config(path_search_start): ...
114
def parse_pyproject_toml(path_config): ...
115
def parse_setup_cfg(path_config): ...
116
```
117

118
[Configuration](./configuration.md)
119

120
### Badge Generation
121

122
Creates SVG and PNG badges displaying docstring coverage percentages. Supports multiple badge styles and automatic color coding based on coverage thresholds.
123

124
```python { .api }
125
def create(
126
    output,
127
    result,
128
    output_format=None,
129
    output_style=None
130
): ...
131

132
def get_badge(
133
    result,
134
    color,
135
    style=None
136
): ...
137
```
138

139
[Badge Generation](./badge-generation.md)
140

141
### Command Line Interface
142

143
Full-featured CLI built with Click framework supporting extensive configuration options, multiple output formats, and integration with CI/CD pipelines.
144

145
```python { .api }
146
def main(ctx, paths, **kwargs): ...
147
```
148

149
[CLI Interface](./cli-interface.md)
150

151
### Utilities
152

153
Helper functions and formatting utilities for file handling, path manipulation, and terminal output formatting.
154

155
```python { .api }
156
def parse_regex(ctx, param, values): ...
157
def smart_open(filename=None, fmode=None): ...
158
def get_common_base(files): ...
159

160
class OutputFormatter:
161
    def __init__(self, config, file=None): ...
162
    def should_markup(self): ...
163
    def set_detailed_markup(self, padded_cells): ...
164
    def set_summary_markup(self, padded_cells): ...
165
    def get_table_formatter(self, table_type): ...
166
```
167

168
[Utilities](./utilities.md)
169

170
### AST Visitor
171

172
AST traversal and node analysis for collecting docstring coverage information from Python source code.
173

174
```python { .api }
175
class CovNode:
176
    name: str
177
    path: str
178
    level: int
179
    lineno: int
180
    covered: bool
181
    node_type: str
182
    is_nested_func: bool
183
    is_nested_cls: bool
184
    parent: object
185

186
class CoverageVisitor:
187
    def __init__(self, filename, config): ...
188
    def visit_Module(self, node): ...
189
    def visit_ClassDef(self, node): ...
190
    def visit_FunctionDef(self, node): ...
191
    def visit_AsyncFunctionDef(self, node): ...
192
```
193

194
[AST Visitor](./ast-visitor.md)
195

196
## Package Constants
197

198
```python { .api }
199
__author__ = "Lynn Root"
200
__version__ = "1.7.0"
201
__email__ = "lynn@lynnroot.com"
202
__description__ = "Interrogate a codebase for docstring coverage."
203
__uri__ = "https://interrogate.readthedocs.io"
204
```
205

206
## Types
207

208
```python { .api }
209
class BaseInterrogateResult:
210
    total: int
211
    covered: int
212
    missing: int
213
    perc_covered: float
214

215
class InterrogateFileResult(BaseInterrogateResult):
216
    filename: str
217
    ignore_module: bool
218
    nodes: list
219
    
220
    def combine(self): ...
221

222
class InterrogateResults(BaseInterrogateResult):
223
    ret_code: int
224
    file_results: dict
225
    
226
    def combine(self): ...
227

228
class CovNode:
229
    name: str
230
    path: str
231
    level: int
232
    lineno: int
233
    covered: bool
234
    node_type: str
235
    is_nested_func: bool
236
    is_nested_cls: bool
237
    parent: object
238

239
class InterrogateConfig:
240
    color: bool = False
241
    docstring_style: str = "sphinx"
242
    fail_under: float = 80.0
243
    ignore_regex: bool = False
244
    ignore_magic: bool = False
245
    ignore_module: bool = False
246
    ignore_private: bool = False
247
    ignore_semiprivate: bool = False
248
    ignore_init_method: bool = False
249
    ignore_init_module: bool = False
250
    ignore_nested_classes: bool = False
251
    ignore_nested_functions: bool = False
252
    ignore_property_setters: bool = False
253
    ignore_property_decorators: bool = False
254
    ignore_overloaded_functions: bool = False
255
    include_regex: bool = False
256
    omit_covered_files: bool = False
257
```