history: | 20090524T134300, brand new docs. |
---|---|
history: | 20090613T164000, final touches for 3.0 |
The API to coverage.py is very simple, contained in a single module called coverage containing a single class, also called coverage. Methods on the coverage object correspond to operations available in the command line interface. For example, a simple use would be:
import coverage
cov = coverage.coverage()
cov.start()
# .. run your code ..
cov.stop()
cov.save()
Programmatic access to Coverage.
To use:
from coverage import coverage
cov = coverage()
cov.start()
#.. blah blah (run your code) blah blah ..
cov.stop()
cov.html_report(directory='covhtml')
Create a new coverage measurement context.
data_file is the base name of the data file to use, defaulting to “.coverage”. data_suffix is appended to data_file to create the final file name. If data_suffix is simply True, then a suffix is created with the machine and process identity included.
cover_pylib is a boolean determining whether Python code installed with the Python interpreter is measured. This includes the Python standard library and any packages installed with the interpreter.
If auto_data is true, then any existing data file will be read when coverage measurement starts, and data will be saved automatically when measurement stops.
If timid is true, then a slower simpler trace function will be used. This is important for some environments where manipulation of tracing functions make the faster more sophisticated trace function not operate properly.
Analyze a module.
morf is a module or a filename. It will be analyzed to determine its coverage statistics. The return value is a 5-tuple:
The analysis uses the source file itself and the current measured coverage data.
Annotate a list of modules.
Each module in morfs is annotated. The source is written to a new file, named with a “,cover” suffix, with each line prefixed with a marker to indicate the coverage of the line. Covered lines have “>”, excluded lines have “-“, and missing lines have “!”.
Combine together a number of similarly-named coverage data files.
All coverage data files whose name starts with data_file (from the coverage() constructor) will be read, and combined together into the current measurements.
Erase previously-collected coverage data.
This removes the in-memory data collected in this session as well as discarding the data file.
Exclude source lines from execution consideration.
regex is a regular expression. Lines matching this expression are not considered executable when reporting code coverage. A list of regexes is maintained; this function adds a new regex to the list. Matching any of the regexes excludes a source line.
Write a summary report to file.
Each module in morfs is listed, with counts of statements, executed statements, missing statements, and a list of lines missed.
Control the use of a data file (incorrectly called a cache).
usecache is true or false, whether to read and write data on disk.
Generate an XML report of coverage results.
The report is compatible with Cobertura reports.