From 0cc8fd18714cb214327a0a58b704401a9efdf8dc Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Thu, 5 Mar 2009 21:21:43 -0500 Subject: Initial coverage.py 3.0 beta 1 --- doc/coverage.px | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 250 insertions(+) create mode 100644 doc/coverage.px (limited to 'doc/coverage.px') diff --git a/doc/coverage.px b/doc/coverage.px new file mode 100644 index 00000000..ffc8b353 --- /dev/null +++ b/doc/coverage.px @@ -0,0 +1,250 @@ + + + +Created. +Updated to 2.5. +Updated to 2.6. +Added a problem description for doctest users. +Updated to 2.7. +Updated to 2.75. +Updated to 2.76. +Updated to 2.77. +Updated to 2.78. +Updated to 2.8. +Updated to 2.80. +Updated to 2.85. + + +

Coverage.py is a Python module that measures code coverage during Python execution. +It uses the code analysis tools and tracing hooks provided in the Python standard +library to determine which lines are executable, and which have been executed. +The original version was written by +Gareth Rees. +I've updated it to determine executable statements more accurately. +

+ +

Installation

+ +

To install coverage, unpack the tar file, and run "setup.py install", +or use "easy_install coverage".

+ + + +

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.
    • +
+ + + + + -- cgit v1.2.1