Skip to content

coverage

coverage documentation

toolroom._stubs.coverage.Coverage

Bases: Tool[_R]

Annotate

Bases: Tool[_R2]

__call__ 

__call__(
    *args: str | PathLike[str],
    data_file: Value = ...,
    debug: Value = ...,
    directory: Value = ...,
    ignore_errors: Flag = ...,
    include: Value = ...,
    keep_combined: Flag = ...,
    omit: Value = ...,
    rcfile: Value = ...,
    **flags: Any,
) -> _R2

Make annotated copies of the given files, marking statements that are executed with > and statements that are missed with !.

Parameters:

Name Type Description Default
data_file Value

Read coverage data for report generation from this file.

 ...
debug Value

Debug options, separated by commas.

 ...
directory Value

Write the output files to DIR.

 ...
ignore_errors Flag

Ignore errors while reading source files.

 ...
include Value

Include only files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
keep_combined Flag

Keep original coverage files, otherwise they are deleted after combining. Added in 7.15.0.

 ...
omit Value

Omit files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
rcfile Value

Specify configuration file.

 ...

Combine

Bases: Tool[_R2]

__call__ 

__call__(
    *args: str | PathLike[str],
    append: Flag = ...,
    data_file: Value = ...,
    debug: Value = ...,
    keep: Flag = ...,
    quiet: Flag = ...,
    rcfile: Value = ...,
    **flags: Any,
) -> _R2

Combine data from multiple coverage files. The combined results are written to a single file representing the union of the data. The positional arguments are data files or directories containing

Parameters:

Name Type Description Default
append Flag

Append data to the data file.

 ...
data_file Value

Base name of the data files to operate on.

 ...
debug Value

Debug options, separated by commas.

 ...
keep Flag

Keep original coverage files, otherwise they are deleted.

 ...
quiet Flag

Don't print messages about what is happening.

 ...
rcfile Value

Specify configuration file.

 ...

Erase

Bases: Tool[_R2]

__call__ 

__call__(
    *,
    data_file: Value = ...,
    debug: Value = ...,
    rcfile: Value = ...,
    **flags: Any,
) -> _R2

Erase previously collected coverage data.

Parameters:

Name Type Description Default
data_file Value

Base name of the data files to operate on.

 ...
debug Value

Debug options, separated by commas.

 ...
rcfile Value

Specify configuration file.

 ...

Html

Bases: Tool[_R2]

__call__ 

__call__(
    *args: str | PathLike[str],
    contexts: Value = ...,
    data_file: Value = ...,
    debug: Value = ...,
    directory: Value = ...,
    fail_under: Value = ...,
    ignore_errors: Flag = ...,
    include: Value = ...,
    keep_combined: Flag = ...,
    omit: Value = ...,
    precision: Value = ...,
    quiet: Flag = ...,
    rcfile: Value = ...,
    show_contexts: Flag = ...,
    skip_covered: Flag = ...,
    skip_empty: Flag = ...,
    title: Value = ...,
    **flags: Any,
) -> _R2

Create an HTML report of coverage results. Each file gets its own page, with the source decorated to show executed, excluded, and missed lines.

Parameters:

Name Type Description Default
contexts Value

Only display data from lines covered in the given contexts. May be repeated: a list emits the flag once per item.

 ...
data_file Value

Read coverage data for report generation from this file.

 ...
debug Value

Debug options, separated by commas.

 ...
directory Value

Write the output files to DIR.

 ...
fail_under Value

Exit with a status of 2 if the total coverage is less than MIN.

 ...
ignore_errors Flag

Ignore errors while reading source files.

 ...
include Value

Include only files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
keep_combined Flag

Keep original coverage files, otherwise they are deleted after combining. Added in 7.15.0.

 ...
omit Value

Omit files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
precision Value

Number of digits after the decimal point to display for reported coverage percentages.

 ...
quiet Flag

Don't print messages about what is happening.

 ...
rcfile Value

Specify configuration file.

 ...
show_contexts Flag

Show contexts for covered lines.

 ...
skip_covered Flag

Skip files with 100% coverage. skip_covered=off emits --no-skip-covered.

 ...
skip_empty Flag

Skip files with no code.

 ...
title Value

A text string to use as the title on the HTML.

 ...

Json

Bases: Tool[_R2]

__call__ 

__call__(
    *args: str | PathLike[str],
    contexts: Value = ...,
    data_file: Value = ...,
    debug: Value = ...,
    fail_under: Value = ...,
    ignore_errors: Flag = ...,
    include: Value = ...,
    keep_combined: Flag = ...,
    o: Value = ...,
    omit: Value = ...,
    pretty_print: Flag = ...,
    quiet: Flag = ...,
    rcfile: Value = ...,
    show_contexts: Flag = ...,
    **flags: Any,
) -> _R2

Generate a JSON report of coverage results.

Parameters:

Name Type Description Default
contexts Value

Only display data from lines covered in the given contexts. May be repeated: a list emits the flag once per item.

 ...
data_file Value

Read coverage data for report generation from this file.

 ...
debug Value

Debug options, separated by commas.

 ...
fail_under Value

Exit with a status of 2 if the total coverage is less than MIN.

 ...
ignore_errors Flag

Ignore errors while reading source files.

 ...
include Value

Include only files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
keep_combined Flag

Keep original coverage files, otherwise they are deleted after combining. Added in 7.15.0.

 ...
o Value

Write the JSON report to this file.

 ...
omit Value

Omit files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
pretty_print Flag

Format the JSON for human readers.

 ...
quiet Flag

Don't print messages about what is happening.

 ...
rcfile Value

Specify configuration file.

 ...
show_contexts Flag

Show contexts for covered lines.

 ...

Report

Bases: Tool[_R2]

__call__ 

__call__(
    *args: str | PathLike[str],
    contexts: Value = ...,
    data_file: Value = ...,
    debug: Value = ...,
    fail_under: Value = ...,
    format: Value = ...,
    ignore_errors: Flag = ...,
    include: Value = ...,
    keep_combined: Flag = ...,
    omit: Value = ...,
    precision: Value = ...,
    rcfile: Value = ...,
    show_missing: Flag = ...,
    skip_covered: Flag = ...,
    skip_empty: Flag = ...,
    sort: Value = ...,
    **flags: Any,
) -> _R2

Report coverage statistics on modules.

Parameters:

Name Type Description Default
contexts Value

Only display data from lines covered in the given contexts. May be repeated: a list emits the flag once per item.

 ...
data_file Value

Read coverage data for report generation from this file.

 ...
debug Value

Debug options, separated by commas.

 ...
fail_under Value

Exit with a status of 2 if the total coverage is less than MIN.

 ...
format Value

Output format, either text (default), markdown, or total.

 ...
ignore_errors Flag

Ignore errors while reading source files.

 ...
include Value

Include only files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
keep_combined Flag

Keep original coverage files, otherwise they are deleted after combining. Added in 7.15.0.

 ...
omit Value

Omit files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
precision Value

Number of digits after the decimal point to display for reported coverage percentages.

 ...
rcfile Value

Specify configuration file.

 ...
show_missing Flag

Show line numbers of statements in each module that weren't executed.

 ...
skip_covered Flag

Skip files with 100% coverage. skip_covered=off emits --no-skip-covered.

 ...
skip_empty Flag

Skip files with no code.

 ...
sort Value

Sort the report by the named column: name, stmts, miss, branch, brpart, or cover.

 ...

Run

Bases: Tool[_R2]

__call__ 

__call__(
    pyfile: str | PathLike[str],
    /,
    *args: str | PathLike[str],
    append: Flag = ...,
    branch: Flag = ...,
    concurrency: Value = ...,
    context: Value = ...,
    data_file: Value = ...,
    debug: Value = ...,
    include: Value = ...,
    module: Flag = ...,
    omit: Value = ...,
    parallel_mode: Flag = ...,
    pylib: Flag = ...,
    rcfile: Value = ...,
    save_signal: Value = ...,
    source: Value = ...,
    timid: Flag = ...,
    **flags: Any,
) -> _R2

Run a Python program, measuring code execution.

Parameters:

Name Type Description Default
append Flag

Append data to the data file.

 ...
branch Flag

Measure branch coverage in addition to statement coverage.

 ...
concurrency Value

Properly measure code using a concurrency library.

 ...
context Value

The context label to record for this coverage run.

 ...
data_file Value

Write the recorded coverage data to this file.

 ...
debug Value

Debug options, separated by commas.

 ...
include Value

Include only files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
module Flag

is an importable Python module, not a script path, to be run as 'python -m' would run it.

 ...
omit Value

Omit files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
parallel_mode Flag

Append a unique suffix to the data file name to collect separate data from multiple processes.

 ...
pylib Flag

Measure coverage even inside the Python installed library, which isn't done by default.

 ...
rcfile Value

Specify configuration file.

 ...
save_signal Value

Specify a signal that will trigger coverage to write its collected data.

 ...
source Value

A list of directories or importable names of code to measure. May be repeated: a list emits the flag once per item.

 ...
timid Flag

Use the slower Python trace function core.

 ...

Xml

Bases: Tool[_R2]

__call__ 

__call__(
    *args: str | PathLike[str],
    data_file: Value = ...,
    debug: Value = ...,
    fail_under: Value = ...,
    ignore_errors: Flag = ...,
    include: Value = ...,
    keep_combined: Flag = ...,
    o: Value = ...,
    omit: Value = ...,
    quiet: Flag = ...,
    rcfile: Value = ...,
    skip_empty: Flag = ...,
    **flags: Any,
) -> _R2

Generate an XML report of coverage results.

Parameters:

Name Type Description Default
data_file Value

Read coverage data for report generation from this file.

 ...
debug Value

Debug options, separated by commas.

 ...
fail_under Value

Exit with a status of 2 if the total coverage is less than MIN.

 ...
ignore_errors Flag

Ignore errors while reading source files.

 ...
include Value

Include only files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
keep_combined Flag

Keep original coverage files, otherwise they are deleted after combining. Added in 7.15.0.

 ...
o Value

Write the XML report to this file.

 ...
omit Value

Omit files whose paths match one of these patterns. May be repeated: a list emits the flag once per item.

 ...
quiet Flag

Don't print messages about what is happening.

 ...
rcfile Value

Specify configuration file.

 ...
skip_empty Flag

Skip files with no code.

 ...

__call__ 

__call__(*args: str | PathLike[str], **flags: Any) -> _R

Coverage.py, version 7.15.4 with C extension

flags 

flags(**flags: Any) -> Self

Bind tool-level global options before the subcommand.

tools.docker.flags(host=...) puts a tool's own options ahead of the verb, where they belong.