Coverage.py options can be specified in a configuration file. This makes it
easier to re-run coverage.py with consistent settings, and also allows for
specification of options that are otherwise only available in the
API.

Configuration files also make it easier to get coverage testing of spawned
sub-processes. See Measuring sub-processes for more details.

The default name for configuration files is .coveragerc, in the same
directory coverage.py is being run in. Most of the settings in the
configuration file are tied to your source code and how it should be measured,
so it should be stored with your source, and checked into source control,
rather than put in your home directory.

A different name for the configuration file can be specified with the
--rcfile=FILE command line option.

Coverage.py will read settings from other usual configuration files if no other
configuration file is used. It will automatically read from “setup.cfg” or
“tox.ini” if they exist. In this case, the section names have “coverage:”
prefixed, so the [run] options described below will be found in the
[coverage:run] section of the file.

A coverage.py configuration file is in classic .ini file format: sections are
introduced by a [section] header, and contain name=value entries.
Lines beginning with # or ; are ignored as comments.

Strings don’t need quotes. Multi-valued strings can be created by indenting
values on multiple lines.

Boolean values can be specified as on, off, true, false, 1,
or 0 and are case-insensitive.

Environment variables can be substituted in by using dollar signs: $WORD
or ${WORD} will be replaced with the value of WORD in the environment.
A dollar sign can be inserted with $$. Missing environment variables
will result in empty strings with no error.

concurrency (multi-string, default “thread”): the name concurrency
libraries in use by the product code. If your program uses multiprocessing,
gevent, greenlet, or eventlet, you must name that library in this
option, or coverage.py will produce very wrong results.

Before version 4.2, this option only accepted a single string.

New in version 4.0.

data_file (string, default “.coverage”): the name of the data file to use
for storing or reporting coverage. This value can include a path to another
directory.

disable_warnings (multi-string): a list of warnings to disable. Warnings
that can be disabled include a short string at the end, the name of the
warning. See Warnings for specific warnings.

include (multi-string): a list of file name patterns, the files to include
in measurement or reporting. Ignored if source is set. See Specifying source files
for details.

note (string): an arbitrary string that will be written to the data file.
You can use the CoverageData.run_infos() method to retrieve this string
from a data file.

omit (multi-string): a list of file name patterns, the files to leave out
of measurement or reporting. See Specifying source files for details.

parallel (boolean, default False): append the machine name, process
id and random number to the data file name to simplify collecting data from
many processes. See Combining data files for more information.

plugins (multi-string): a list of plugin package names. See Plug-ins
for more information.

source (multi-string): a list of packages or directories, the source to
measure during execution. If set, include is ignored. See Specifying source files
for details.

timid (boolean, default False): use a simpler but slower trace method.
This uses PyTracer instead of CTracer, and is only needed in very unusual
circumstances. Try this if you get seemingly impossible results.

The entries in this section are lists of file paths that should be considered
equivalent when combining data from different machines:

[paths]source=src//jenkins/build/*/srcc:\myproj\src

The names of the entries are ignored, you may choose any name that you like.
The value is a list of strings. When combining data with the combine
command, two file paths will be combined if they start with paths from the same
list.

The first value must be an actual file path on the machine where the reporting
will happen, so that source code can be found. The other values can be file
patterns to match against the paths of collected data, or they can be absolute
or relative file paths on the current machine.

exclude_lines (multi-string): a list of regular expressions. Any line of
your source code that matches one of these regexes is excluded from being
reported as missing. More details are in Excluding code from coverage.py. If you use this
option, you are replacing all the exclude regexes, so you’ll need to also
supply the “pragma: no cover” regex if you still want to use it.

fail_under (float): a target coverage percentage. If the total coverage
measurement is under this value, then exit with a status code of 2. If you
specify a non-integral value, you must also set [report]precision properly
to make use of the decimal places. A setting of 100 will fail any value under
100, regardless of the number of decimal places of precision.

include (multi-string): a list of file name patterns, the files to include
in reporting. See Specifying source files for details.

omit (multi-string): a list of file name patterns, the files to leave out
of reporting. See Specifying source files for details.

partial_branches (multi-string): a list of regular expressions. Any line
of code that matches one of these regexes is excused from being reported as
a partial branch. More details are in Branch coverage measurement. If you use this option,
you are replacing all the partial branch regexes so you’ll need to also
supply the “pragma: no branch” regex if you still want to use it.

precision (integer): the number of digits after the decimal point to
display for reported coverage percentages. The default is 0, displaying for
example “87%”. A value of 2 will display percentages like “87.32%”. This
setting also affects the interpretation of the fail_under setting.

show_missing (boolean, default False): when running a summary report, show
missing lines. See Coverage summary for more information.

skip_covered (boolean, default False): Don’t include files in the report
that are 100% covered files. See Coverage summary for more information.

extra_css (string): the path to a file of CSS to apply to the HTML report.
The file will be copied into the HTML output directory. Don’t name it
“style.css”. This CSS is in addition to the CSS normally used, though you can
overwrite as many of the rules as you like.

title (string, default “Coverage report”): the title to use for the report.
Note this is text, not HTML.

Values particular to XML reporting. The values in the [report] section
also apply to XML output, where appropriate.

output (string, default “coverage.xml”): where to write the XML report.

package_depth (integer, default 99): controls which directories are
identified as packages in the report. Directories deeper than this depth are
not reported as packages. The default is that all directories are reported as
packages.