You will have a coverage module for importing, and a coverage command for command line execution.

There is also a set of tests for coverage: test_coverage.py and coverage_coverage.py. These will only be of interest if you want to modify coverage.py.

Command-line usage

The command line interface hasn't changed from the original version. All of the original instructions still hold. Read that document if you haven't used coverage.py before. Here I'll describe the changes I've introduced.

The identification of executable statements is now more accurate. Docstrings are not flagged as missing statements, nor are "global" statements. Complex multi-line if and elif conditions are handled properly.

Statements can now be excluded from consideration. This is useful if you have lines of code that you know will not be executed, and you don't want the coverage report to be filled with their noise. For example, you may have interactive test clauses at the ends of your modules that your test suite will not execute:

This suite of code can be excluded from the coverage report by adding a specially-formed comment:

The #pragma line can be placed on any line of code. If the line contains the colon that introduces a suite of statements, the entire suite is excluded. Annotated files (created with "coverage -a") will prefix excluded lines with "-".

Programmatic usage

Again, the original instructions still hold, but I've made a few additions.

The form of the exclusion marker can be changed using the exclude() method. It takes a regular expression, and excludes any line that contains a match:

As the example shows, the marker pattern doesn't have to be a comment. Any number of regular expressions can be added by calling exclude a number of times.

The use of a file to hold coverage data can be suppressed by calling use_cache(0) before calling start().

The analysis(module) function still returns a 4-tuple (filename, statement list, missing list, missing string). A new analysis2(module) function extends the return to a 5-tuple (filename, statement list, excluded list, missing list, missing string).

The annotate(modules) function is available to annotate a list of modules, and the annotate_file(filename, statements, excluded, missing) function provides the bulk of annotation in a directly callable form.

Known Problems

Older versions of doctest interfere with coverage's tracing of statements, and you may get reports that none of your code is executing. Use this patch to doctest.py if you are experiencing problems.

History

Changes I've made over time:

Version 2.85, September 14 2008

• Add support for finding source files in eggs.
• Don't check for morf's being instances of ModuleType, instead use duck typing so that pseudo-modules can participate. Thanks, Imri Goldberg.
• Use os.realpath as part of the fixing of filenames so that symlinks won't confuse things. Thanks, Patrick Mezard.

Version 2.80, May 25 2008

• Coverage.py is now installed as an egg, making integration with nose smoother. If you had an older version of coverage, remove the old coverage.py in the command directory (for example, /usr/bin or \Python25\Scripts).
• Source files are opened in rU mode, preventing problems with errant line endings.

Version 2.78, September 30 2007

• Better handling of Python source in files that don't end with .py. Thanks, Ben Finney.

Version 2.77, July 29 2007

• Better packaging, including Cheeseshop goodness.

Version 2.76, July 23 2007

• Added support for the overlooked "with" statement in Python 2.5.

Version 2.75, July 22 2007

• The way multi-line statements are handled has been revamped, allowing coverage.py to support Python 2.5.
• Functions with just a docstring and a pass statement no longer report the pass as uncovered.

Version 2.7, July 21 2007

• The #pragma:nocover comment syntax is ignored by default, so programmatic invocations of coverage also attend to those declarations.
• Constants in the middle of functions are properly ignored, since they won't be executed.
• Code exec'ed from strings no longer clutters reports with exceptions. That code will be ignored by coverage.py, since we can't get the source code to analyze it anyway.
• Minor fixes: Linux current directory handling (thanks Guillaume Chazarain), globbing for Windows (thanks Noel O'Boyle), and Python 2.2 compatibility (thanks Catherine Proulx).

Version 2.6, August 22 2006

• Function decorators are now handled properly (thanks Joseph Tate).
• Fixed a few bugs with the --omit option (thanks Mark van der Wal and Sigve Tjora)
• Coverage data files can be written from several processes at once with the -p and -c options (thanks Geoff Bache).

Version 2.5, December 4 2005

• Multi-threaded programs now have all threads properly measured (thanks Martin Fuzzey).
• The report() method now takes an optional file argument which defaults to stdout.
• Adapted Greg Rogers' patch to allow omitting files by directory from the report and annotation, sorting files, and reporting files relatively.
• coverage.py can now recursively measure itself under test!

Version 2.2, December 31 2004

• Made it possible to use keyword arguments with the module global functions (thanks Allen).

Version 2.1, December 14 2004

• Fix some backward-compatibility problems with the analysis function.
• Refactor annotate to provide annotate_file.

Version 2, December 12 2004

• My first version.

Problems

Coverage.py has been tested successfully on Pythons 2.2.3, 2.3.5, 2.4.3, 2.5.1 and 2.6a3. If you have code that it doesn't handle properly, send it to me! Be sure to mention the version of Python you are using.

See also

• Gareth Rees's original page about the design of coverage.py
• Sancho is a unit testing framework that includes code coverage measurement.
• pycover, another Python implementation of code coverage.
• The trace module in the Python standard library.
• My blog, where topics often include those of interest to both casual and serious Python users.