===============
python-coverage
===============

-------------------------------------------------
measure code coverage of Python program execution
-------------------------------------------------

:Author: Ned Batchelder <ned@nedbatchelder.com>
:Author: |author|
:Date: 2015-09-20
: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| **erase**
    Erase previously collected coverage data.

|command| **help**
    Get help on using coverage.py.

|command| **html**
    Create an HTML report.

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


GLOBAL OPTIONS
==============

**--help**, **-h**
    Describe how to use coverage.py, in general or a command.

**--rcfile** `RCFILE`
    Specify configuration file `RCFILE`. Defaults to ``.coveragerc``.

**--omit** `PATTERN` [ , ... ]
    Omit files when their file name matches one of these PATTERNs.
    Usually needs quoting on the command line.

**--include** `PATTERN` [ , ... ]
    Include only files whose paths match one of these
    PATTERNs. Accepts shell-style wildcards, which must be quoted.

**--debug** `DEBUGOPT`,...
    Debug options `DEBUGOPT`, separated by commas.


COMMAND REFERENCE
=================

**annotate** [ `option` ... ]

    Options:

    \-d `DIR`, --directory=`DIR`
        Write the output files to DIR.

    \-i, --ignore-errors
        Ignore errors while reading source files.

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

    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.

**erase**

    Erase previously collected coverage data.

**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:

    \-d `DIR`, --directory `DIR`
        Write the output files to `DIR`.

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

    \--skip-covered
        Skip files with 100% coverage.

    \--title `TITLE`
        Use the text string `TITLE` as the title on the HTML.

**report** [ `option` ... ] [ `MODULE` ... ]

    Report coverage statistics on each `MODULE`.

    Options:

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

    \-m, --show-missing
        Show line numbers of statements in each module that weren't
        executed.

    \--skip-covered
        Skip files with 100% coverage.

**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 `LIB`
        Properly measure code using a concurrency library. Valid values are:
        thread, gevent, greenlet, eventlet, multiprocessing.

    \-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:

    \--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 XML report to `OUTFILE`. Defaults to ``coverage.xml``.


ENVIRONMENT VARIABLES
=====================

COVERAGE_FILE

    Path to the file where coverage measurements are collected to and
    reported from. Default: ``.coverage`` in the current working directory.

HISTORY
=======

The |command| command is a Python program which calls the ``coverage``
Python library to do all the work.

The library 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:: <ben+python@benfinney.id.au>

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