Coverage.py API

The API to coverage.py is very simple, contained in a single module called coverage. Most of the interface is in a single class, called Coverage. Methods on the Coverage object correspond roughly to operations available in the command line interface. For example, a simple use would be:

import coverage

cov = coverage.Coverage()
cov.start()

# .. call your code ..

cov.stop()
cov.save()

cov.html_report()

The Coverage class

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, debug=None, concurrency=None)

Programmatic access to coverage.py.

To use:

from coverage import Coverage

cov = Coverage()
cov.start()
#.. call your code ..
cov.stop()
cov.html_report(directory='covhtml')

__init__(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, debug=None, concurrency=None)

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 configuration file to read:

• If it is ”.coveragerc”, it is interpreted as if it were True, for backward compatibility.
• If it is a string, it is the name of the file to read. If the file can’t be read, it is an error.
• If it is True, then a few standard files names are tried (”.coveragerc”, “setup.cfg”). It is not an error for these files to not be found.
• If it is False, then no configuration 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.

debug is a list of strings indicating what debugging information is desired.

concurrency is a string indicating the concurrency library being used in the measured code. Without this, coverage.py will get incorrect results. Valid strings are “greenlet”, “eventlet”, “gevent”, or “thread” (the default).

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(data_paths=None)

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.

data_paths is a list of files or directories from which data should be combined. If no list is passed, then the data files from the directory indicated by the current data file (probably the current directory) will be combined.

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

Get the collected data and reset the collector.

Also warn about various problems collecting data.

Returns a CoverageData, the collected coverage data.

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, extra_css=None, title=None)

Generate an HTML report.

The HTML is written to directory. The file “index.html” is the overview starting point, with links to more detailed pages for individual modules.

extra_css is a path to a file of other CSS to apply on the page. It will be copied into the HTML directory.

title is a text string (not HTML) to use as the title of the HTML report.

See coverage.report() for other arguments.

Returns a float, the total percentage covered.

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, skip_covered=False)

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. Files that match will be included in the report. Files matching omit will not be included in the report.

Returns a float, the total percentage covered.

save()

Save the collected coverage data to the data file.

start()

Start measuring code coverage.

Coverage measurement actually occurs in functions called after start is invoked. Statements in the same scope as start won’t be measured.

Once you invoke start, you must also call stop eventually, or your process might not shut down cleanly.

stop()

Stop measuring code coverage.

sys_info()

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

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.

Returns a float, the total percentage covered.

The CoverageData class

class coverage.CoverageData(debug=None)

Manages collected coverage data, including file storage.

This class is the public supported API to the data coverage.py collects during program execution. It includes information about what code was executed.

Note

The file format is not documented or guaranteed. It will change in the future, in possibly complicated ways. Use this API to avoid disruption.

There are a number of kinds of data that can be collected:

• lines: the line numbers of source lines that were executed. These are always available.
• arcs: pairs of source and destination line numbers for transitions between source lines. These are only available if branch coverage was used.
• file tracer names: the module names of the file tracer plugins that handled each file in the data.
• run information: information about the program execution. This is written during “coverage run”, and then accumulated during “coverage combine”.

To read a coverage.py data file, use read_file(), or read() if you have an already-opened file. You can then access the line, arc, or file tracer data with lines(), arcs(), or file_tracer(). Run information is available with run_infos().

The has_arcs() method indicates whether arc data is available. You can get a list of the files in the data with measured_files(). A summary of the line data is available from line_counts(). As with most Python containers, you can determine if there is any data at all by using this object as a boolean value.

Most data files will be created by coverage.py itself, but you can use methods here to create data files if you like. The set_lines(), set_arcs(), and set_file_tracers() methods add data, in ways that are convenient for coverage.py. The add_run_info() method adds key-value pairs to the run information.

To add a file without any measured data, use touch_file().

You write to a named file with write_file(), or to an already opened file with write().

You can clear the data in memory with erase(). Two data collections can be combined by using update() on one CoverageData, passing it the other.

__init__(debug=None)

Create a CoverageData.

debug is a DebugControl object for writing debug messages.

add_run_info(**kwargs)

Add information about the run.

Keywords are arbitrary, and are stored in the run dictionary. Values must be JSON serializable. You may use this function more than once, but repeated keywords overwrite each other.

add_to_hash(filename, hasher)

Contribute filename‘s data to the hasher.

hasher is a coverage.misc.Hasher instance to be updated with the file’s data. It should only get the results data, not the run data.

arcs(filename)

Get the list of arcs executed for a file.

If the file was not measured, returns None. A file might be measured, and have no arcs executed, in which case an empty list is returned.

If the file was executed, returns a list of 2-tuples of integers. Each pair is a starting line number and an ending line number for a transition from one line to another. The list is in no particular order.

Negative numbers have special meaning. If the starting line number is -N, it represents an entry to the code object that starts at line N. If the ending ling number is -N, it’s an exit from the code object that starts at line N.

erase()

Erase the data in this object.

file_tracer(filename)

Get the plugin name of the file tracer for a file.

Returns the name of the plugin that handles this file. If the file was measured, but didn’t use a plugin, then “” is returned. If the file was not measured, then None is returned.

has_arcs()

Does this data have arcs?

Arc data is only available if branch coverage was used during collection.

Returns a boolean.

line_counts(fullpath=False)

Return a dict summarizing the line coverage data.

Keys are based on the filenames, and values are the number of executed lines. If fullpath is true, then the keys are the full pathnames of the files, otherwise they are the basenames of the files.

Returns a dict mapping filenames to counts of lines.

lines(filename)

Get the list of lines executed for a file.

If the file was not measured, returns None. A file might be measured, and have no lines executed, in which case an empty list is returned.

If the file was executed, returns a list of integers, the line numbers executed in the file. The list is in no particular order.

measured_files()

A list of all files that had been measured.

read(file_obj)

Read the coverage data from the given file object.

Should only be used on an empty CoverageData object.

read_file(filename)

Read the coverage data from filename into this object.

run_infos()

Return the list of dicts of run information.

For data collected during a single run, this will be a one-element list. If data has been combined, there will be one element for each original data file.

set_arcs(arc_data)

Add measured arc data.

arc_data is { filename: { (l1,l2): None, ... }, ...}

Do not call this more than once, it will not update data, it only sets data.

set_file_tracers(file_tracers)

Add per-file plugin information.

file_tracers is { filename: plugin_name, ... }

set_lines(line_data)

Add executed line data.

line_data is a dictionary mapping filenames to dictionaries:

{ filename: { lineno: None, ... }, ...}

Do not call this more than once, it will not update data, it only sets data.

touch_file(filename)

Ensure that filename appears in the data, empty if needed.

update(other_data, aliases=None)

Update this data with data from another CoverageData.

If aliases is provided, it’s a PathAliases object that is used to re-map paths to match the local machine’s.

write(file_obj)

Write the coverage data to file_obj.

write_file(filename)

Write the coverage data to filename.

Starting coverage.py automatically

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

coverage.process_startup()

Call this at Python start-up 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()