=============== python-coverage =============== ---------------------------- Measure Python code coverage ---------------------------- :Author: Ned Batchelder :Author: |author| :Date: 2022-12-03 :Copyright: Apache 2.0 license, attribution and disclaimer required. :Manual section: 1 :Manual group: Coverage.py .. |command| replace:: **python-coverage** .. To test this file: $ rst2man < doc/python-coverage.1.txt | groff -man -Tascii SYNOPSIS ======== | |command| `command` [ `option` ... ] | |command| **help** [ `command` ] DESCRIPTION =========== |command| executes a Python program and measures which of its statements are executed and which are not, and reports these coverage measurements. COMMAND OVERVIEW ================ |command| **annotate** Annotate source files with execution information. |command| **combine** Combine a number of data files. |command| **debug** Display information about the internals of coverage.py. |command| **erase** Erase previously collected coverage data. |command| **help** Get help on using coverage.py. |command| **html** Create an HTML report. |command| **json** Create a JSON report of coverage results. |command| **report** Report coverage stats on modules. |command| **run** Run a Python program and measure code execution. |command| **xml** Create an XML report of coverage results. |command| **lcov** Create an LCOV report of coverage results. GLOBAL OPTIONS ============== **--help**, **-h** Describe how to use coverage.py, in general or a command. **--rcfile** `RCFILE` Specify configuration file `RCFILE`. By default '.coveragerc', 'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried. **--debug** `DEBUGOPT`,... Debug options `DEBUGOPT`, separated by commas. COMMAND REFERENCE ================= **annotate** [ `option` ... ] Options: \-d `DIR`, --directory=`DIR` Write the output files to DIR. \--data-file `INFILE` Read coverage data for report generation from this file. Defaults to '.coverage'. \-i, --ignore-errors Ignore errors while reading source files. \--include `PATTERN` [ , ... ] Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted. \--omit `PATTERN` [ , ... ] Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line. **combine** [ `option` ... ] [ `PATH` ... ] Combine data from multiple coverage files collected with ``run -p``. The combined results are written to a single file representing the union of the data. Unless --keep is provided the original input coverage files are deleted. If `PATH` is specified, they are files or directories containing data to be combined. Options: \--append Append coverage data to .coverage, otherwise it starts clean each time. \--data-file `DATAFILE` Base name of the data files to operate on. Defaults to '.coverage'. \--keep Keep original coverage data files. \-q, --quiet Don't print messages about what is happening. **debug** `TOPIC` ... Display information about the internals of coverage.py, for diagnosing problems. Topics are: ``data`` to show a summary of the collected data; ``sys`` to show installation information; ``config`` to show the configuration; ``premain`` to show what is calling coverage; ``pybehave`` to show internal flags describing Python behavior. **erase** Erase previously collected coverage data. Options: \--data-file `DATAFILE` Base name of the data files to operate on. Defaults to '.coverage'. **help** [ `command` ] Describe how to use coverage.py. **html** [ `option` ... ] [ `MODULE` ... ] Create an HTML report of the coverage of each `MODULE` file. Each file gets its own page, with the source decorated to show executed, excluded, and missed lines. Options: \--contexts `PAT` [ , ... ] Only include contexts that match one of the regex patterns. \-d `DIR`, --directory `DIR` Write the output files to `DIR`. \--data-file `INFILE` Read coverage data for report generation from this file. Defaults to '.coverage'. \--fail-under `MIN` Exit with a status of 2 if the total coverage is less than `MIN`. \-i, --ignore-errors Ignore errors while reading source files. \--include `PATTERN` [ , ... ] Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted. \--omit `PATTERN` [ , ... ] Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line. \--precision `N` Number of digits after the decimal point to display for reported coverage percentages. \-q, --quiet Don't print messages about what is happening. \--show-contexts Annotate lines with the contexts that executed them. \--skip-covered Skip files with 100% coverage. \--no-skip-covered Disable ``--skip-covered``. \--skip-empty Skip files with no code. \--title `TITLE` Use the text string `TITLE` as the title on the HTML. **json** [ `option` ... ] [ `MODULE` ... ] Generate a JSON report of coverage results. \--contexts `PAT` [ , ... ] Only include contexts that match one of the regex patterns. \--data-file `INFILE` Read coverage data for report generation from this file. Defaults to '.coverage'. \--fail-under `MIN` Exit with a status of 2 if the total coverage is less than `MIN`. \-i, --ignore-errors Ignore errors while reading source files. \--include `PATTERN` [ , ... ] Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted. \-o `OUTFILE` Write the JSON report to `OUTFILE`. Defaults to ``coverage.json``. \--omit `PATTERN` [ , ... ] Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line. \--pretty-print Format the JSON for human readers. \-q, --quiet Don't print messages about what is happening. \--show-contexts Include information about the contexts that executed each line. **lcov** [ `option` ... ] [ `MODULE` ... ] Create an LCOV report of the coverage results. Options: \--data-file `INFILE` Read coverage data for report generation from this file. Defaults to '.coverage'. \--fail-under `MIN` Exit with a status of 2 if the total coverage is less than `MIN`. \-i, --ignore-errors Ignore errors while reading source files. \-o `OUTFILE` Write the LCOV report to `OUTFILE`. Defaults to ``coverage.lcov``. \--include `PATTERN` [ , ... ] Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted. \--omit `PATTERN` [ , ... ] Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line. \-q, --quiet Don't print messages about what is happening. **report** [ `option` ... ] [ `MODULE` ... ] Report coverage statistics on each `MODULE`. Options: \--contexts `PAT` [ , ... ] Only include contexts that match one of the regex patterns. \--data-file `INFILE` Read coverage data for report generation from this file. Defaults to '.coverage'. \--fail-under `MIN` Exit with a status of 2 if the total coverage is less than `MIN`. \--format `FORMAT` Output format, either text (default), markdown, or total. \-i, --ignore-errors Ignore errors while reading source files. \--include `PATTERN` [ , ... ] Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted. \--omit `PATTERN` [ , ... ] Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line. \-m, --show-missing Show line numbers of statements in each module that weren't executed. \--precision `N` Number of digits after the decimal point to display for reported coverage percentages. \--skip-covered Skip files with 100% coverage. \--no-skip-covered Disable ``--skip-covered``. \--skip-empty Skip files with no code. \--sort `COLUMN` Sort the report by thee named column: `name`, `stmts`, `miss`, `branch`, `brpart`, or `cover`. **run** [ `options` ... ] `PROGRAMFILE` [ `program_options` ] Run a Python program `PROGRAMFILE`, measuring code execution. Options: \-a, --append Append coverage data to .coverage, otherwise it is started clean with each run. \--branch Measure branch coverage in addition to statement coverage. \--concurrency `LIBS` Properly measure code using a concurrency library. Valid values are: thread, gevent, greenlet, eventlet, multiprocessing, or a comma-list of them. \--context `CONTEXT` The context label to record for this coverage run. \--data-file `OUTFILE` Write the recorded coverage data to this file. Defaults to '.coverage'. \--include `PATTERN` [ , ... ] Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted. \-m `PROGRAMFILE` is interpreted as a module name. \--omit `PATTERN` [ , ... ] Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line. \-L, --pylib Measure coverage even inside the Python installed library, which isn't done by default. \-p, --parallel-mode Append the machine name, process id and random number to the ``.coverage`` data file name to simplify collecting data from many processes. \--source `SOURCE` ... A list of packages or directories of code to be measured. \--timid Use a simpler but slower trace method. Try this if you get seemingly impossible results! **xml** [ `options` ... ] [ `MODULES` ... ] Generate an XML report of coverage results on each `MODULE`. Options: \--data-file `INFILE` Read coverage data for report generation from this file. Defaults to '.coverage'. \--fail-under `MIN` Exit with a status of 2 if the total coverage is less than `MIN`. \-i, --ignore-errors Ignore errors while reading source files. \--include `PATTERN` [ , ... ] Include only files whose paths match one of these PATTERNs. Accepts shell-style wildcards, which must be quoted. \--omit `PATTERN` [ , ... ] Omit files when their file name matches one of these PATTERNs. Usually needs quoting on the command line. \-o `OUTFILE` Write the XML report to `OUTFILE`. Defaults to ``coverage.xml``. \-q, --quiet Don't print messages about what is happening. \--skip-empty Skip files with no code. ENVIRONMENT VARIABLES ===================== COVERAGE_FILE Path to the file where coverage measurements are collected to and reported from. Default: ``.coverage`` in the current working directory. COVERAGE_RCFILE Path to the configuration file, often named ``.coveragerc``. HISTORY ======= The |command| command is a Python program which calls the ``coverage`` Python library to do all the work. It was originally developed by Gareth Rees, and is now developed by Ned Batchelder and many others. This manual page was written by |author|. .. |author| replace:: |authorname| |authoremail| .. |authorname| replace:: Ben Finney .. |authoremail| replace:: .. Local variables: mode: rst coding: utf-8 time-stamp-format: "%:y-%02m-%02d" time-stamp-start: "^:Date:[ ]+" time-stamp-end: "$" time-stamp-line-limit: 20 End: vim: filetype=rst fileencoding=utf-8 :