[Checkins] SVN: z3c.coverage/trunk/ Nicer PyPI description. Doctests are tests, not docs.
Marius Gedminas
cvs-admin at zope.org
Wed Oct 24 14:35:09 UTC 2012
Log message for revision 128139:
Nicer PyPI description. Doctests are tests, not docs.
Changed:
U z3c.coverage/trunk/CHANGES.txt
U z3c.coverage/trunk/README.txt
U z3c.coverage/trunk/setup.py
-=-
Modified: z3c.coverage/trunk/CHANGES.txt
===================================================================
--- z3c.coverage/trunk/CHANGES.txt 2012-10-24 12:44:49 UTC (rev 128138)
+++ z3c.coverage/trunk/CHANGES.txt 2012-10-24 14:35:08 UTC (rev 128139)
@@ -1,10 +1,11 @@
+Changes
=======
-CHANGES
-=======
1.3.1 (unreleased)
------------------
+- Nicer PyPI description. Doctests are tests, not docs.
+
- ``coveragereport`` now accepts ``--path-alias``.
- ``coveragereport``: new color step between yellow (90%) and green (100%), a
Modified: z3c.coverage/trunk/README.txt
===================================================================
--- z3c.coverage/trunk/README.txt 2012-10-24 12:44:49 UTC (rev 128138)
+++ z3c.coverage/trunk/README.txt 2012-10-24 14:35:08 UTC (rev 128139)
@@ -1,6 +1,206 @@
-This package produces a nice HTML representation of the coverage data
-generated by the Zope test runner, ``zope.testing``. It will also
-highlighting Python syntax if you have ``enscript`` installed.
+============
+z3c.coverage
+============
-There's also a script to check for differences in coverage and report
-any regressions (increases in the number of untested lines).
+This package contains tools to work with Python coverage data.
+
+``coveragereport`` produces HTML reports from coverage data, with
+syntax-highlighted source code and per-package aggregate numbers.
+
+``coveragediff`` compares two sets of coverage reports and reports
+regressions, that is, increases in the number of untested lines of code.
+
+.. contents::
+
+
+Using coveragereport
+====================
+
+::
+
+ $ coveragereport --help
+ Usage: coveragereport [options] [inputpath [outputdir]]
+
+ Converts coverage reports to HTML. If the input path is omitted, it defaults
+ to coverage or .coverage, whichever exists. If the output directory is
+ omitted, it defaults to inputpath + /report or ./coverage-reports, depending
+ on whether the input path points to a directory or a file.
+
+ Options:
+ -h, --help show this help message and exit
+ -q, --quiet be quiet
+ -v, --verbose be verbose (default)
+ --strip-prefix=PREFIX
+ strip base directory from filenames loaded from
+ .coverage
+ --path-alias=PATH=LOCALPATH
+ define path mappings for filenames loaded from
+ .coverage
+
+Example use with ``zope.testrunner``::
+
+ $ bin/test --coverage=coverage
+ $ coveragereport
+ $ ln -s mypackage.html coverage/report/index.html
+ $ xdg-open coverage/report/index.html
+ $ xdg-open coverage/report/all.html
+
+Example use with ``nose`` and ``coverage.py``::
+
+ $ nosetests --with-coverage --cover-erase
+ $ coveragereport --strip-prefix=/full/path/to/source/
+ $ ln -s mypackage.html coverage-reports/index.html
+ $ xdg-open coverage-reports/index.html
+ $ xdg-open coverage-reports/all.html
+
+Sample report:
+
+.. image:: http://i.imgur.com/mkqA3.png
+
+.. note:: You need `enscript <http://www.gnu.org/software/enscript/>`_
+ installed and available in your ``$PATH`` if you want syntax
+ highlighting.
+
+
+Using coveragediff
+==================
+
+::
+
+ Usage: coveragediff [options] olddir newdir
+
+ Options:
+ -h, --help show this help message and exit
+ --include=REGEX only consider files matching REGEX
+ --exclude=REGEX ignore files matching REGEX
+ --email=ADDR send the report to a given email address (only if
+ regressions were found)
+ --from=ADDR set the email sender address
+ --subject=SUBJECT set the email subject
+ --web-url=BASEURL include hyperlinks to HTML-ized coverage reports at a
+ given URL
+
+Usage example with ``zope.testrunner``::
+
+ $ bin/test --coverage=coverage
+ $ vi src/...
+ $ mv coverage coverage.old
+ $ bin/test --coverage=coverage
+ $ coveragediff coverage.old coverage
+
+You cannot use ``coveragediff`` with ``coverage.py`` data. More on that below.
+
+Output example::
+
+ $ coveragediff coverage.old coverage
+ my.package.module: 36 new lines of untested code
+ my.package.newmodule: new file with 15 lines of untested code (out of 23)
+
+Output with clickable links::
+
+ $ coveragediff coverage.old coverage --web-url=http://example.com/coverage
+ my.package.module: 36 new lines of untested code
+ See http://example.com/coverage/my.package.module.html
+
+ my.package.newmodule: new file with 15 lines of untested code (out of 23)
+ See http://example.com/coverage/my.package.newmodule.html
+
+Output via email, convenient for continuous integration::
+
+ $ coveragediff coverage.old coverage --web-url=http://example.com/coverage \
+ --email 'Developers <dev at exmaple.com>' \
+ --from 'Buildbot <buildbot at example.com>'
+
+That last example doesn't produce any output, but sends an email (via SMTP
+to localhost:25).
+
+
+Getting coverage data
+=====================
+
+zope.testrunner
+---------------
+
+`zope.testrunner <http://pypi.python.org/pypi/zope.testrunner>`_ can
+produce a directory full of files named ``dotted.package.name.cover``
+that contain source code annotated with coverage information. To get
+them, use ::
+
+ bin/test --coverage=outdir/
+
+Both ``coveragereport`` and ``coveragediff`` accept this as inputs.
+
+
+coverage.py
+-----------
+
+`coverage.py <http://pypi.python.org/pypi/coverage>`_ can produce
+a ``.coverage`` file, which is actually a Python pickle containing
+(incomplete) coverage information. To get it, use ::
+
+ coverage run bin/testrunner
+
+``coveragereport`` can take the ``.coverage`` file as an input, but it
+also needs access to the matching source files. And you have to manually
+specify the absolute pathname prefix of your source tree so that the
+report know how to translate filenames into dotted package names. Also,
+it's not enough to have *absolute* pathnames, you need to supply the
+*canonical* absolute pathname (with no symlink segments), such as returned
+by ``os.path.realpath``. This is very inconvenient. Sorry.
+
+``coveragediff`` is unable to compare two ``.coverage`` files and report
+regressions. One reason for that is the incompleteness of the data format
+(the pickle contains line numbers of executed statements, but doesn't
+say which lines contain code and which ones are
+blank/comments/continuation lines/excluded source lines). The other
+reason is simpler: nobody wrote the code. `;)`
+
+Unfortunately ``coverage annotate`` does not produce files compatible
+with ``coveragereport``/``coveragediff``. This could also be remedied
+if somebody wrote a patch.
+
+
+.. note:: If you want to use a ``.coverage`` file produced on another machine
+ or simply in a different working directory, you will need to
+ tell ``coveragereport`` how to adjust the absolute filenames so that
+ the sources can be found. Use the ``--path-alias`` option for that.
+ Alternatively you could use ``coverage combine`` to manipulate the
+ ``.coverage`` file itself, as described in the documentation.
+
+.. note:: ``.coverage`` files are Python pickles, which has important
+ security ramifications. You can craft a Pickle file that executes
+ arbitrary code during load time. **Do not ever attempt to use
+ pickles received from untrusted sources.**
+
+
+trace.py
+--------
+
+The ``*.cover`` annotated-source format produced by ``zope.testrunner``
+actually comes from the Python standard library module `trace.py
+<http://docs.python.org/library/trace>`_. You can probably use trace.py
+directly. I've never tried.
+
+
+Frequently Asked Questions
+==========================
+
+Why use z3c.coverage instead of coverage html?
+----------------------------------------------
+
+Some people prefer the look of the reports produced by z3c.coverage.
+Some people find per-package coverage summaries or the tree-like navigation
+convenient.
+
+Should I use zope.testrunner's built-in coverage, or coverage run bin/test?
+-----------------------------------------------------------------------------
+
+``coverage.py`` is *much* faster, but using it (and hooking it up to z3c.coverage)
+is perhaps less convenient. E.g. if you use ``zc.buildout 1.5.x`` with
+``zc.recipe.testrunner``, you will be unable to use ``coverage run bin/test``
+because of mystic semi-broken site isolation magic of the former.
+
+Did anyone actually ask any of these questions?
+-----------------------------------------------
+
+Does asking myself count?
Modified: z3c.coverage/trunk/setup.py
===================================================================
--- z3c.coverage/trunk/setup.py 2012-10-24 12:44:49 UTC (rev 128138)
+++ z3c.coverage/trunk/setup.py 2012-10-24 14:35:08 UTC (rev 128139)
@@ -30,13 +30,6 @@
long_description=(
read('README.txt')
+ '\n\n' +
- 'Detailed Documentation\n'
- '**********************'
- + '\n\n' +
- read('src', 'z3c', 'coverage', 'README.txt')
- + '\n\n' +
- read('src', 'z3c', 'coverage', 'coveragediff.txt')
- + '\n\n' +
read('CHANGES.txt')
),
license="ZPL 2.1",
More information about the checkins
mailing list