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.

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.

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.