The Coverage class

class coverage.Coverage(data_file=MISSING, data_suffix=None, cover_pylib=None, auto_data=False, timid=None, branch=None, config_file=True, source=None, source_pkgs=None, omit=None, include=None, debug=None, concurrency=None, check_preimported=False, context=None, messages=False)

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")

A context manager is available to do the same thing:

cov = Coverage()
with cov.collect():
    #.. call your code ..
cov.html_report(directory="covhtml")

Note: in keeping with Python custom, names starting with underscore are not part of the public API. They might stop working at any point. Please limit yourself to documented methods to avoid problems.

Methods can raise any of the exceptions described in Coverage exceptions.

Parameters:
  • data_file (FilePath | DefaultValue | None)

  • data_suffix (str | bool | None)

  • cover_pylib (bool | None)

  • auto_data (bool)

  • timid (bool | None)

  • branch (bool | None)

  • config_file (FilePath | bool)

  • source (Iterable[str] | None)

  • source_pkgs (Iterable[str] | None)

  • omit (str | Iterable[str] | None)

  • include (str | Iterable[str] | None)

  • debug (Iterable[str] | None)

  • concurrency (str | Iterable[str] | None)

  • check_preimported (bool)

  • context (str | None)

  • messages (bool)

__init__(data_file=MISSING, data_suffix=None, cover_pylib=None, auto_data=False, timid=None, branch=None, config_file=True, source=None, source_pkgs=None, omit=None, include=None, debug=None, concurrency=None, check_preimported=False, context=None, messages=False)

Many of these arguments duplicate and override values that can be provided in a configuration file. Parameters that are missing here will use values from the config file.

data_file is the base name of the data file to use. The config value defaults to “.coverage”. None can be provided to prevent writing a data file. 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”, “tox.ini”). 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.

source_pkgs is a list of package names. It works the same as source, but can be used to name packages where the name can also be interpreted as a file path.

include and omit are lists of file name 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 if these libraries are in use. Valid strings are “greenlet”, “eventlet”, “gevent”, “multiprocessing”, or “thread” (the default). This can also be a list of these strings.

If check_preimported is true, then when coverage is started, the already-imported files will be checked to see if they should be measured by coverage. Importing measured files before coverage is started can mean that code is missed.

context is a string to use as the static context label for collected data.

If messages is true, some messages will be printed to stdout indicating what is happening.

Added in version 4.0: The concurrency parameter.

Added in version 4.2: The concurrency parameter can now be a list of strings.

Added in version 5.0: The check_preimported and context parameters.

Added in version 5.3: The source_pkgs parameter.

Added in version 6.0: The messages parameter.

Parameters:
Return type:

None

analysis(morf)

Like analysis2 but doesn’t return excluded line numbers.

Parameters:

morf (ModuleType | str)

Return type:

tuple[str, list[int], list[int], str]

analysis2(morf)

Analyze a module.

morf is a module or a file name. It will be analyzed to determine its coverage statistics. The return value is a 5-tuple:

  • The file name 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.

Parameters:

morf (ModuleType | str)

Return type:

tuple[str, list[int], list[int], list[int], str]

annotate(morfs=None, directory=None, ignore_errors=None, omit=None, include=None, contexts=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 report() for other arguments.

Parameters:
Return type:

None

clear_exclude(which='exclude')

Clear the exclude list.

Parameters:

which (str)

Return type:

None

collect()

A context manager to start/stop coverage measurement collection.

Added in version 7.3.

Return type:

Iterator[None]

combine(data_paths=None, strict=False, keep=False)

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.

If strict is true, then it is an error to attempt to combine when there are no data files to combine.

If keep is true, then original input data files won’t be deleted.

Added in version 4.0: The data_paths parameter.

Added in version 4.3: The strict parameter.

Parameters:
Return type:

None

classmethod current()

Get the latest started Coverage instance, if any.

Returns: a Coverage instance, or None.

Added in version 5.0.

Return type:

Coverage | None

erase()

Erase previously collected coverage data.

This removes the in-memory data collected in this session as well as discarding the data file.

Return type:

None

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.

Parameters:
Return type:

None

get_data()

Get the collected data.

Also warn about various problems collecting data.

Returns a coverage.CoverageData, the collected coverage data.

Added in version 4.0.

Return type:

CoverageData

get_exclude_list(which='exclude')

Return a list of excluded regex strings.

which indicates which list is desired. See exclude() for the lists that are available, and their meaning.

Parameters:

which (str)

Return type:

list[str]

get_option(option_name)

Get an option from the configuration.

option_name is a colon-separated string indicating the section and option name. For example, the branch option in the [run] section of the config file would be indicated with “run:branch”.

Returns the value of the option. The type depends on the option selected.

As a special case, an option_name of "paths" will return an dictionary with the entire [paths] section value.

Added in version 4.0.

Parameters:

option_name (str)

Return type:

bool | int | float | str | list[str] | None

html_report(morfs=None, directory=None, ignore_errors=None, omit=None, include=None, extra_css=None, title=None, skip_covered=None, show_contexts=None, contexts=None, skip_empty=None, precision=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 report() for other arguments.

Returns a float, the total percentage covered.

Note

The HTML report files are generated incrementally based on the source files and coverage results. If you modify the report files, the changes will not be considered. You should be careful about changing the files in the report folder.

Parameters:
Return type:

float

json_report(morfs=None, outfile=None, ignore_errors=None, omit=None, include=None, contexts=None, pretty_print=None, show_contexts=None)

Generate a JSON report of coverage results.

Each module in morfs is included in the report. outfile is the path to write the file to, “-” will write to stdout.

pretty_print is a boolean, whether to pretty-print the JSON output or not.

See report() for other arguments.

Returns a float, the total percentage covered.

Added in version 5.0.

Parameters:
Return type:

float

lcov_report(morfs=None, outfile=None, ignore_errors=None, omit=None, include=None, contexts=None)

Generate an LCOV report of coverage results.

Each module in morfs is included in the report. outfile is the path to write the file to, “-” will write to stdout.

See report() for other arguments.

Added in version 6.3.

Parameters:
Return type:

float

load()

Load previously-collected coverage data from the data file.

Return type:

None

report(morfs=None, show_missing=None, ignore_errors=None, file=None, omit=None, include=None, skip_covered=None, contexts=None, skip_empty=None, precision=None, sort=None, output_format=None)

Write a textual summary report to file.

Each module in morfs is listed, with counts of statements, executed statements, missing statements, and a list of lines missed.

If show_missing is true, then details of which lines or branches are missing will be included in the report. If ignore_errors is true, then a failure while reporting a single file will not stop the entire report.

file is a file-like object, suitable for writing.

output_format determines the format, either “text” (the default), “markdown”, or “total”.

include is a list of file name patterns. Files that match will be included in the report. Files matching omit will not be included in the report.

If skip_covered is true, don’t report on files with 100% coverage.

If skip_empty is true, don’t report on empty files (those that have no statements).

contexts is a list of regular expression strings. Only data from dynamic contexts that match one of those expressions (using re.search) will be included in the report.

precision is the number of digits to display after the decimal point for percentages.

All of the arguments default to the settings read from the configuration file.

Returns a float, the total percentage covered.

Added in version 4.0: The skip_covered parameter.

Added in version 5.0: The contexts and skip_empty parameters.

Added in version 5.2: The precision parameter.

Added in version 7.0: The format parameter.

Parameters:
Return type:

float

save()

Save the collected coverage data to the data file.

Return type:

None

set_option(option_name, value)

Set an option in the configuration.

option_name is a colon-separated string indicating the section and option name. For example, the branch option in the [run] section of the config file would be indicated with "run:branch".

value is the new value for the option. This should be an appropriate Python value. For example, use True for booleans, not the string "True".

As an example, calling:

cov.set_option("run:branch", True)

has the same effect as this configuration file:

[run]
branch = True

As a special case, an option_name of "paths" will replace the entire [paths] section. The value should be a dictionary.

Added in version 4.0.

Parameters:
Return type:

None

start()

Start measuring code coverage.

Coverage measurement is only collected 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.

The collect() method is a context manager to handle both starting and stopping collection.

Return type:

None

stop()

Stop measuring code coverage.

Return type:

None

switch_context(new_context)

Switch to a new dynamic context.

new_context is a string to use as the dynamic context label for collected data. If a static context is in use, the static and dynamic context labels will be joined together with a pipe character.

Coverage collection must be started already.

Added in version 5.0.

Parameters:

new_context (str)

Return type:

None

xml_report(morfs=None, outfile=None, ignore_errors=None, omit=None, include=None, contexts=None, skip_empty=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 report() for other arguments.

Returns a float, the total percentage covered.

Parameters:
Return type:

float