path: root/doc/coverage.px

<?xml version="1.0" encoding="utf-8" ?>
<page title='coverage'>
<history>
<what when='20041212T183900'>Created.</what>
<what when='20051204T131100'>Updated to 2.5.</what>
<what when='20060822T210600'>Updated to 2.6.</what>
<what when='20061001T164600'>Added a problem description for doctest users.</what>
<what when='20070721T211900'>Updated to 2.7.</what>
<what when='20070722T154900'>Updated to 2.75.</what>
<what when='20070723T201400'>Updated to 2.76.</what>
<what when='20070729T201400'>Updated to 2.77.</what>
<what when='20080107T071400'>Updated to 2.78.</what>
<what when='20080525T135029'>Updated to 2.8.</what>
<what when='20080525T172606'>Updated to 2.80.</what>
<what when='20081012T080912'>Updated to 2.85.</what>
</history>

<p>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
<a href='code/modules/rees-coverage.html'>Gareth Rees</a>.
I've updated it to determine executable statements more accurately.
</p>

<h1>Installation</h1>

<p>To install coverage, unpack the tar file, and run "setup.py install",
or use "easy_install coverage".</p>

<download file='coverage-2.85.tar.gz' path='code/modules/coverage-2.85.tar.gz' />

<p>You will have a coverage module for importing, and a coverage command
for command line execution.</p>

<p>There is also a set of tests for coverage:
<a href='code/modules/test_coverage.py'>test_coverage.py</a> and
<a href='code/modules/coverage_coverage.py'>coverage_coverage.py</a>.
These will only be of interest if you want to modify coverage.py.
</p>

<h1>Command-line usage</h1>

<p>The command line interface hasn't changed from the original version.
All of the
<a href='code/modules/rees-coverage.html'>original instructions</a>
still hold.
Read that document if you haven't used coverage.py before.
Here I'll describe the changes I've introduced.</p>

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

<p>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:</p>

<code lang='python'><![CDATA[
#.. all the real code ..

if __name__ == '__main__':
    # Run the test code from the command-line, for convenience
    blah.run('sample')
]]></code>

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

<code lang='python'><![CDATA[
#.. all the real code ..

if __name__ == '__main__':   #pragma: no cover
    # Run the test code from the command-line, for convenience
    blah.run('sample')
]]></code>

<p>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 "-".</p>


<h1>Programmatic usage</h1>

<p>Again, the
<a href='code/modules/rees-coverage.html'>original instructions</a>
still hold, but I've made a few additions.</p>

<p>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:</p>

<code lang='python'><![CDATA[
# Don't count branches that will never execute
coverage.exclude('if super_debug:')
]]></code>

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

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

<p>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).</p>

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


<h1>Known Problems</h1>

<p>Older versions of doctest interfere with coverage's tracing of statements, and you
may get reports that none of your code is executing.  
Use <a href='http://svn.zope.org/Zope3/trunk/src/zope/testing/doctest.py?rev=28679&amp;r1=28703&amp;r2=28705'>this patch to doctest.py</a>
if you are experiencing problems.</p>


<h1>History</h1>

<p>Changes I've made over time:</p>

<h2>Version 2.85, September 14 2008</h2>

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

<h2>Version 2.80, May 25 2008</h2>

<ul>
    <li>Coverage.py is now installed as an egg, making integration with
    <a href='http://www.somethingaboutorange.com/mrl/projects/nose/'>nose</a> 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).</li>
    <li>Source files are opened in rU mode, preventing problems with errant line endings.</li>
</ul>

<h2>Version 2.78, September 30 2007</h2>

<ul>
    <li>Better handling of Python source in files that don't end with .py.
    Thanks, Ben Finney.</li>
</ul>

<h2>Version 2.77, July 29 2007</h2>

<ul>
<li>Better packaging, including Cheeseshop goodness.</li>
</ul>

<h2>Version 2.76, July 23 2007</h2>

<ul>
<li>Added support for the overlooked "with" statement in Python 2.5.</li>
</ul>

<h2>Version 2.75, July 22 2007</h2>

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

<h2>Version 2.7, July 21 2007</h2>

<ul>
<li>The #pragma:nocover comment syntax is ignored by default, so programmatic
invocations of coverage also attend to those declarations.</li>
<li>Constants in the middle of functions are properly ignored, since they won't be executed.</li>
<li>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.</li>
<li>Minor fixes: Linux current directory handling (thanks Guillaume Chazarain),
globbing for Windows (thanks Noel O'Boyle), and Python 2.2 compatibility (thanks Catherine Proulx).</li>
</ul>

<h2>Version 2.6, August 22 2006</h2>

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

<h2>Version 2.5, December 4 2005</h2>

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

<h2>Version 2.2, December 31 2004</h2>

<ul>
<li>Made it possible to use keyword arguments with the module global functions (thanks Allen).</li>
</ul>

<h2>Version 2.1, December 14 2004</h2>

<ul>
<li>Fix some backward-compatibility problems with the analysis function.</li>
<li>Refactor annotate to provide annotate_file.</li>
</ul>

<h2>Version 2, December 12 2004</h2>

<ul>
<li>My first version.</li>
</ul>


<h1>Problems</h1>

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



<h1>See also</h1>

<ul>
<li>Gareth Rees's <a href='code/modules/rees-design.html'>original page</a> about the design of coverage.py</li>
<li><a href='http://www.mems-exchange.org/software/sancho/'>Sancho</a> is a unit testing framework that includes code coverage measurement.</li>
<li><a href='http://www.geocities.com/drew_csillag/pycover.html'>pycover</a>, another Python implementation of code coverage.</li>
<li>The <a href='http://docs.python.org/library/trace.html'>trace module</a> in the Python standard library.</li>
<li><a href='blog'>My blog</a>, where topics often include those of interest to both casual and serious Python users.</li>
</ul>

<googleads/>
<pagecomments/>

</page>