0
# Coverage.py
1

2
Coverage.py is a comprehensive code coverage measurement tool for Python that tracks which lines of code are executed during test runs or program execution. It provides detailed reporting capabilities including HTML, XML, JSON, and LCOV formats, supports branch coverage analysis to track conditional execution paths, and integrates seamlessly with popular testing frameworks like pytest and unittest.
3

4
## Package Information
5

6
- **Package Name**: coverage
7
- **Language**: Python
8
- **Installation**: `pip install coverage`
9
- **License**: Apache-2.0
10
- **Documentation**: https://coverage.readthedocs.io/
11

12
## Core Imports
13

14
```python
15
import coverage
16
```
17

18
Most common usage patterns:
19

20
```python
21
from coverage import Coverage
22
from coverage.data import CoverageData
23
```
24

25
## Basic Usage
26

27
### Command-line Usage
28

29
```bash
30
# Run your program with coverage measurement
31
coverage run my_program.py
32

33
# Generate a report
34
coverage report
35

36
# Generate HTML report
37
coverage html
38

39
# Combine multiple coverage files
40
coverage combine
41
```
42

43
### Programmatic Usage
44

45
```python
46
import coverage
47

48
# Create a Coverage instance
49
cov = coverage.Coverage()
50

51
# Start measurement
52
cov.start()
53

54
# Run your code here
55
import my_module
56
result = my_module.some_function()
57

58
# Stop measurement
59
cov.stop()
60

61
# Save data
62
cov.save()
63

64
# Generate report
65
cov.report()
66

67
# Generate HTML report
68
cov.html_report()
69
```
70

71
## Architecture
72

73
Coverage.py uses a layered architecture for flexible code measurement:
74

75
- **Coverage Class**: Main control interface managing configuration, measurement lifecycle, and reporting
76
- **Tracers**: Low-level execution tracking (C extension tracer for performance, Python fallback)
77
- **Data Storage**: SQLite-based storage with CoverageData interface for persistence and querying
78
- **Reporters**: Multiple output formats (console, HTML, XML, JSON, LCOV, annotated source)
79
- **Plugin System**: Extensible architecture for custom file tracers and configurers
80
- **Configuration**: Flexible configuration via pyproject.toml, .coveragerc, or programmatic setup
81

82
This design enables coverage.py to work across different Python implementations (CPython, PyPy), handle complex execution environments (multiprocessing, async code), and integrate with various testing frameworks and CI/CD systems.
83

84
## Capabilities
85

86
### Core Coverage Measurement
87

88
Primary coverage measurement and control functionality including starting/stopping measurement, data persistence, configuration management, and basic analysis. The Coverage class serves as the main entry point for all coverage operations.
89

90
```python { .api }
91
class Coverage:
92
    def __init__(
93
        self,
94
        data_file=None,
95
        data_suffix=None,
96
        cover_pylib=None,
97
        auto_data=False,
98
        timid=None,
99
        branch=None,
100
        config_file=True,
101
        source=None,
102
        source_pkgs=None,
103
        source_dirs=None,
104
        omit=None,
105
        include=None,
106
        debug=None,
107
        concurrency=None,
108
        check_preimported=False,
109
        context=None,
110
        messages=False,
111
        plugins=None
112
    ): ...
113
    
114
    def start(self) -> None: ...
115
    def stop(self) -> None: ...
116
    def save(self) -> None: ...
117
    def load(self) -> None: ...
118
    def erase(self) -> None: ...
119
    def get_data(self) -> CoverageData: ...
120
```
121

122
[Core Coverage Measurement](./core-coverage.md)
123

124
### Data Storage and Retrieval
125

126
Coverage data storage, querying, and manipulation through the CoverageData class. Handles persistence of execution data, context information, and provides query interfaces for analysis and reporting.
127

128
```python { .api }
129
class CoverageData:
130
    def __init__(
131
        self,
132
        basename=None,
133
        suffix=None,
134
        warn=None,
135
        debug=None,
136
        no_disk=False
137
    ): ...
138
    
139
    def measured_files(self) -> set[str]: ...
140
    def lines(self, filename: str) -> set[int] | None: ...
141
    def arcs(self, filename: str) -> set[tuple[int, int]] | None: ...
142
    def has_arcs(self) -> bool: ...
143
```
144

145
[Data Storage and Retrieval](./data-storage.md)
146

147
### Report Generation
148

149
Multiple output formats for coverage reports including console text, HTML with highlighting, XML (Cobertura), JSON, LCOV, and annotated source files. Each reporter provides different visualization and integration capabilities.
150

151
```python { .api }
152
def report(
153
    self,
154
    morfs=None,
155
    show_missing=None,
156
    ignore_errors=None,
157
    file=None,
158
    omit=None,
159
    include=None,
160
    skip_covered=None,
161
    contexts=None,
162
    skip_empty=None,
163
    precision=None,
164
    sort=None,
165
    output_format=None
166
) -> float: ...
167

168
def html_report(
169
    self,
170
    morfs=None,
171
    directory=None,
172
    ignore_errors=None,
173
    omit=None,
174
    include=None,
175
    contexts=None,
176
    skip_covered=None,
177
    skip_empty=None,
178
    show_contexts=None,
179
    title=None,
180
    precision=None
181
) -> float: ...
182
```
183

184
[Report Generation](./reporting.md)
185

186
### Plugin System
187

188
Extensible plugin architecture for custom file tracers, configurers, and dynamic context switchers. Enables coverage measurement for non-Python files and custom execution environments.
189

190
```python { .api }
191
class CoveragePlugin:
192
    def file_tracer(self, filename: str) -> FileTracer | None: ...
193
    def file_reporter(self, filename: str) -> FileReporter | str: ...
194
    def dynamic_context(self, frame) -> str | None: ...
195
    def configure(self, config) -> None: ...
196

197
class FileTracer:
198
    def source_filename(self) -> str: ...
199
    def line_number_range(self, frame) -> tuple[int, int]: ...
200

201
class FileReporter:
202
    def lines(self) -> set[int]: ...
203
    def arcs(self) -> set[tuple[int, int]]: ...
204
    def source(self) -> str: ...
205
```
206

207
[Plugin System](./plugins.md)
208

209
### Configuration Management
210

211
Comprehensive configuration system supporting multiple file formats (pyproject.toml, .coveragerc), command-line options, and programmatic configuration. Manages source inclusion/exclusion, measurement options, and output settings.
212

213
```python { .api }
214
def get_option(self, option_name: str): ...
215
def set_option(self, option_name: str, value) -> None: ...
216
```
217

218
[Configuration Management](./configuration.md)
219

220
### Exception Handling
221

222
Complete exception hierarchy for coverage-related errors including data file issues, source code problems, plugin errors, and configuration problems.
223

224
```python { .api }
225
class CoverageException(Exception): ...
226
class NoDataError(CoverageException): ...
227
class NoSource(CoverageException): ...
228
class ConfigError(Exception): ...
229
class PluginError(CoverageException): ...
230
```
231

232
[Exception Handling](./exceptions.md)
233

234
## Types
235

236
```python { .api }
237
import os
238
import types
239
from typing import Union, Tuple
240

241
# Type aliases for common coverage types
242
FilePath = Union[str, os.PathLike[str]]
243
LineNumber = int
244
Arc = Tuple[LineNumber, LineNumber]
245
ModuleOrFilename = Union[types.ModuleType, str]
246

247
# Version information
248
version_info: Tuple[int, int, int, str, int]
249
__version__: str
250
```