Coverage API

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()

The coverage module

class coverage.coverage(data_file=None, data_suffix=False, cover_pylib=False, auto_data=False, timid=False)

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.

analysis(morf)

Like analysis2 but doesn’t return excluded line numbers.

analysis2(morf)

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 filename for the module.
• A list of line numbers of executable statements.
• A list of line numbers of excluded statements.
• A list of line numbers of statements not run (missing from execution).
• A readable formatted string of the missing line numbers.

The analysis uses the source file itself and the current measured coverage data.

annotate(morfs=None, directory=None, ignore_errors=False, omit_prefixes=None)

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 “!”.

clear_exclude()

Clear the exclude list.

combine()

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()

Erase previously-collected coverage data.

This removes the in-memory data collected in this session as well as discarding the data file.

exclude(regex)

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.

get_exclude_list()

Return the list of excluded regex patterns.

html_report(morfs=None, directory=None, ignore_errors=False, omit_prefixes=None)

Generate an HTML report.

load()

Load previously-collected coverage data from the data file.

report(morfs=None, show_missing=True, ignore_errors=False, file=None, omit_prefixes=None)

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.

save()

Save the collected coverage data to the data file.

start()

Start measuring code coverage.

stop()

Stop measuring code coverage.

use_cache(usecache)

Control the use of a data file (incorrectly called a cache).

usecache is true or false, whether to read and write data on disk.

xml_report(morfs=None, ignore_errors=False, omit_prefixes=None)

Generate an XML report of coverage results.

The report is compatible with Cobertura reports.