# 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.

  This class is the public supported API to the data that 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 data file is currently a SQLite database file, with a documented schema. The schema is subject to change though, so be careful about querying it directly. Use this API if you can to isolate yourself from changes.

  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.

  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 either stores lines, or arcs, but not both.

  A data file is associated with the data when the `CoverageData` is created, using the parameters basename, suffix, and no_disk. The base name can be queried with `base_filename()`, and the actual file name being used is available from `data_filename()`.

  To read an existing coverage.py data file, use `read()`. You can then access the line, arc, or file tracer data with `lines()`, `arcs()`, or `file_tracer()`.

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

  The contexts for each line in a file can be read with `contexts_by_lineno()`.

  To limit querying to certain contexts, use `set_query_context()` or `set_query_contexts()`. These will narrow the focus of subsequent `lines()`, `arcs()`, and `contexts_by_lineno()` calls. The set of all measured context names can be retrieved with `measured_contexts()`.

  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.

  To record data for contexts, use `set_context()` to set a context to be used for subsequent `add_lines()` and `add_arcs()` calls.

  To add a source file without any measured data, use `touch_file()`, or `touch_files()` for a list of such files.

  Write the data to its file with `write()`.

  You can clear the data in memory with `erase()`. Data for specific files can be removed from the database with `purge_files()`.

  Two data collections can be combined by using `update()` on one `CoverageData`, passing it the other.

  Data in a `CoverageData` can be serialized and deserialized with `dumps()` and `loads()`.

  The methods used during the coverage.py collection phase (`add_lines()`, `add_arcs()`, `set_context()`, and `add_file_tracers()`) are thread-safe. Other methods may not be.

  Parameters:

    - basename (FilePath | None) –

    - suffix (str | bool | None) –

    - no_disk (bool) –

    - warn (TWarnFn | None) –

    - debug (TDebugCtl | None) –

  __init__(basename=None, suffix=None, no_disk=False, warn=None, debug=None)

    Create a `CoverageData` object to hold coverage-measured data.

    Parameters:

      - basename (str) – the base name of the data file, defaulting to “.coverage”. This can be a path to a file in another directory.

      - suffix (str or bool) – has the same meaning as the data_suffix argument to `coverage.Coverage`.

      - no_disk (bool) – if True, keep all data in memory, and don’t write any disk file.

      - warn (TWarnFn | None) – a warning callback function, accepting a warning message argument.

      - debug (TDebugCtl | None) – a DebugControl object (optional)

    Return type:

      None

  add_arcs(arc_data)

    Add measured arc data.

    arc_data is a dictionary mapping file names to iterables of pairs of ints:

        { filename: { (l1,l2), (l1,l2), ... }, ...}

    Parameters:

      arc_data (Mapping[str, Collection[Tuple[int, int]]]) –

    Return type:

      None

  add_file_tracers(file_tracers)

    Add per-file plugin information.

    file_tracers is { filename: plugin_name, … }

    Parameters:

      file_tracers (Mapping[str, str]) –

    Return type:

      None

  add_lines(line_data)

    Add measured line data.

    line_data is a dictionary mapping file names to iterables of ints:

        { filename: { line1, line2, ... }, ...}

    Parameters:

      line_data (Mapping[str, Collection[int]]) –

    Return type:

      None

  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.

    Parameters:

      filename (str) –

    Return type:

      list[Tuple[int, int]] | None

  base_filename()

    The base filename for storing data.

    New in version 5.0.

    Return type:

      str

  contexts_by_lineno(filename)

    Get the contexts for each line in a file.

    Returns:

      A dict mapping line numbers to a list of context names.

    Parameters:

      filename (str) –

    Return type:

      dict[int, list[str]]

    New in version 5.0.

  data_filename()

    Where is the data stored?

    New in version 5.0.

    Return type:

      str

  dumps()

    Serialize the current data to a byte string.

    The format of the serialized data is not documented. It is only suitable for use with `loads()` in the same version of coverage.py.

    Note that this serialization is not what gets stored in coverage data files. This method is meant to produce bytes that can be transmitted elsewhere and then deserialized with `loads()`.

    Returns:

      A byte string of serialized data.

    Return type:

      bytes

    New in version 5.0.

  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.

    Parameters:

      parallel (bool) –

    Return type:

      None

  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.

    Parameters:

      filename (str) –

    Return type:

      str | None

  has_arcs()

    Does the database have arcs (True) or lines (False).

    Return type:

      bool

  lines(filename)

    Get the list of lines executed for a source 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.

    Parameters:

      filename (str) –

    Return type:

      list[int] | None

  loads(data)

    Deserialize data from `dumps()`.

    Use with a newly-created empty `CoverageData` object. It’s undefined what happens if the object already has data in it.

    Note that this is not for reading data from a coverage data file. It is only for use on data you produced with `dumps()`.

    Parameters:

      data (bytes) – A byte string of serialized data produced by `dumps()`.

    Return type:

      None

    New in version 5.0.

  measured_contexts()

    A set of all contexts that have been measured.

    New in version 5.0.

    Return type:

      set[str]

  measured_files()

    A set of all files that have been measured.

    Note that a file may be mentioned as measured even though no lines or arcs for that file are present in the data.

    Return type:

      set[str]

  purge_files(filenames)

    Purge any existing coverage data for the given filenames.

    New in version 7.2.

    Parameters:

      filenames (Collection[str]) –

    Return type:

      None

  read()

    Start using an existing data file.

    Return type:

      None

  set_context(context)

    Set the current context for future `add_lines()` etc.

    context is a str, the name of the context to use for the next data additions. The context persists until the next `set_context()`.

    New in version 5.0.

    Parameters:

      context (str | None) –

    Return type:

      None

  set_query_context(context)

    Set a context for subsequent querying.

    The next `lines()`, `arcs()`, or `contexts_by_lineno()` calls will be limited to only one context. context is a string which must match a context exactly. If it does not, no exception is raised, but queries will return no data.

    New in version 5.0.

    Parameters:

      context (str) –

    Return type:

      None

  set_query_contexts(contexts)

    Set a number of contexts for subsequent querying.

    The next `lines()`, `arcs()`, or `contexts_by_lineno()` calls will be limited to the specified contexts. contexts is a list of Python regular expressions. Contexts will be matched using `re.search`. Data will be included in query results if they are part of any of the contexts matched.

    New in version 5.0.

    Parameters:

      contexts (Sequence[str] | None) –

    Return type:

      None

  classmethod sys_info()

    Our information for Coverage.sys_info.

    Returns a list of (key, value) pairs.

    Return type:

      list[tuple[str, Any]]

  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.

    Parameters:

      - filename (str) –

      - plugin_name (str) –

    Return type:

      None

  touch_files(filenames, plugin_name=None)

    Ensure that filenames appear in the data, empty if needed.

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

    Parameters:

      - filenames (Collection[str]) –

      - plugin_name (str | None) –

    Return type:

      None

  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. Note: aliases is None only when called directly from the test suite.

    Parameters:

      - other_data (CoverageData) –

      - aliases (PathAliases | None) –

    Return type:

      None

  write()

    Ensure the data is written to the data file.

    Return type:

      None