Coverage API

history:20090524T134300, brand new docs. history:20090613T164000, final touches for 3.0 history:20100221T151500, docs for 3.3 (on the plane back from PyCon) history:20100725T211700, updated for 3.4.

The API to coverage.py is very simple, contained in a single module called coverage. Most of the interface is in 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=None, cover_pylib=None, auto_data=False, timid=None, branch=None, config_file=True, source=None, omit=None, include=None)

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

data_file is the base name of the data file to use, defaulting to ”.coverage”. data_suffix is appended (with a dot) 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 and simpler trace function will be used. This is important for some environments where manipulation of tracing functions breaks the faster trace function.

If branch is true, then branch coverage will be measured in addition to the usual statement coverage.

config_file determines what config file to read. If it is a string, it is the name of the config file to read. If it is True, then a standard file is read (”.coveragerc”). If it is False, then no file is read.

source is a list of file paths or package names. Only code located in the trees indicated by the file paths or package names will be measured.

include and omit are lists of filename patterns. Files that match include will be measured, files that match omit will not. Each will also accept a single string argument.

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=None, omit=None, include=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 ”!”.

See coverage.report() for other arguments.

clear_exclude(which='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, which='exclude')

Exclude source lines from execution consideration.

A number of lists of regular expressions are maintained. Each list selects lines that are treated differently during reporting.

which determines which list is modified. The “exclude” list selects lines that are not considered executable at all. The “partial” list indicates lines with branches that are not taken.

regex is a regular expression. The regex is added to the specified list. If any of the regexes in the list is found in a line, the line is marked for special treatment during reporting.

get_exclude_list(which='exclude')

Return a list of excluded regex patterns.

which indicates which list is desired. See exclude for the lists that are available, and their meaning.

html_report(morfs=None, directory=None, ignore_errors=None, omit=None, include=None)

Generate an HTML report.

See coverage.report() for other arguments.

load()

Load previously-collected coverage data from the data file.

report(morfs=None, show_missing=True, ignore_errors=None, file=None, omit=None, include=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.

include is a list of filename patterns. Modules whose filenames match those patterns will be included in the report. Modules matching omit will not be included in the report.

save()

Save the collected coverage data to the data file.

start()

Start measuring code coverage.

stop()

Stop measuring code coverage.

sysinfo()

Return a list of (key, value) pairs showing internal information.

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, outfile=None, ignore_errors=None, omit=None, include=None)

Generate an XML report of coverage results.

The report is compatible with Cobertura reports.

Each module in morfs is included in the report. outfile is the path to write the file to, “-” will write to stdout.

See coverage.report() for other arguments.

Starting coverage automatically

This function is used to start coverage measurement automatically when Python starts. See Measuring subprocesses for details.

coverage.process_startup()

Call this at Python startup to perhaps measure coverage.

If the environment variable COVERAGE_PROCESS_START is defined, coverage measurement is started. The value of the variable is the config file to use.

There are two ways to configure your Python installation to invoke this function when Python starts:

1. Create or append to sitecustomize.py to add these lines:

   import coverage
   coverage.process_startup()
   

2. Create a .pth file in your Python installation containing:

   import coverage; coverage.process_startup()