The CoverageData class

New in version 4.0.

class coverage.CoverageData(basename=None, suffix=None, no_disk=False, warn=None, debug=None)

Manages collected coverage data, including file storage.

TODO: This is the 4.x docstring. Update it for 5.0.

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.

A data file is associated with the data when the CoverageData is created.

To read a coverage.py data file, use read(). 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 source file without any measured data, use touch_file().

Write the data to its 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__(basename=None, suffix=None, no_disk=False, warn=None, debug=None)

Initialize self. See help(type(self)) for accurate signature.

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, ... }, ...}
base_filename()

The base filename for storing data.

data_filename()

Where is the data stored?

dump()

Write a dump of the database.

erase(parallel=False)

Erase the data in this object.

If parallel is true, then also deletes data files created from the basename by parallel-mode.

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.

measured_contexts()

A set of all contexts that have been measured.

measured_files()

A set of all files that had been measured.

set_context(context)

Set the current context for future add_lines etc.

set_query_contexts(contexts)

Set query contexts for future lines, arcs etc. calls.

touch_file(filename, plugin_name='')

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

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

update(other_data, aliases=None)

Update this data with data from several other CoverageData instances.

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

write()

Write the collected coverage data to a file.