The CoverageData class

New in version 4.0.

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. It does not include information from the analysis phase, to determine what lines could have been executed, or what lines were not executed.

Note

The file format is not documented or guaranteed. It will change in the future, in possibly complicated ways. Do not read coverage.py data files directly. 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”.

Lines, arcs, and file tracer names are stored for each source file. File names in this API are case-sensitive, even on platforms with case-insensitive file systems.

To read a coverage.py data file, use read_file(), or read_fileobj() 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 add_lines(), add_arcs(), and add_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_fileobj().

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

Add measured arc data.

arc_data is a dictionary mapping file names to dictionaries:

{ filename: { (l1,l2): None, ... }, ...}
add_file_tracers(file_tracers)

Add per-file plugin information.

file_tracers is { filename: plugin_name, … }

add_lines(line_data)

Add measured line data.

line_data is a dictionary mapping file names to dictionaries:

{ filename: { lineno: None, ... }, ...}
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 file names, 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 file names 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(filename)

Read the coverage data from filename into this object.

read_fileobj(file_obj)

Read the coverage data from the given file object.

Should only be used on an empty CoverageData 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.

touch_file(filename, plugin_name='')

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

plugin_name is the name of the plugin resposible for this file. It is used to associate the right filereporter, etc.

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

Write the coverage data to filename.

write_fileobj(file_obj)

Write the coverage data to file_obj.