diff options
| -rw-r--r-- | checkeol.py | 1 | ||||
| -rw-r--r-- | doc/changes.rst | 346 | ||||
| -rw-r--r-- | doc/index.rst | 232 |
3 files changed, 290 insertions, 289 deletions
diff --git a/checkeol.py b/checkeol.py index 7af9d8b0..6464893c 100644 --- a/checkeol.py +++ b/checkeol.py @@ -33,4 +33,5 @@ check_files("coverage/htmlfiles", ["*.html", "*.css", "*.js"]) check_files("test", ["*.py"]) check_files("test", ["*,cover"], trail_white=False) check_file("setup.py") +check_files("doc", ["*.rst"]) check_files(".", ["*.txt"]) diff --git a/doc/changes.rst b/doc/changes.rst index 67f5e8aa..0ec5bedc 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -1,173 +1,173 @@ -.. _change:
-
-====================================
-Major change history for coverage.py
-====================================
-
-:history: 20090524T134300, brand new docs.
-:history: 20090613T164000, final touches for 3.0
-:history: 20090706T205000, changes for 3.0.1
-:history: 20091004T170700, changes for 3.1
-:history: 20091128T072200, changes for 3.2
-:history: 20091205T161525, 3.2 final
-:history: 20100221T151900, changes for 3.3
-
-These are the major changes for coverage.py. For a more complete change
-history, see the `CHANGES.txt`_ file in the source tree.
-
-.. _CHANGES.txt: http://bitbucket.org/ned/coveragepy/src/tip/CHANGES.txt
-
-
-Version 3.3
------------
-
-- Settings are now read from a .coveragerc file. A specific file can be
- specified on the command line with --rcfile=FILE. The name of the file can
- be programmatically set with the `config_file` argument to the coverage()
- constructor, or reading a config file can be disabled with
- `config_file=False`.
-
-- Added coverage.process_start to enable coverage measurement when Python
- starts.
-
-- Parallel data file names now have a random number appended to them in
- addition to the machine name and process id. Also, parallel data files
- combined with "coverage combine" are deleted after they're combined, to clean
- up unneeded files. Fixes `issue 40`_.
-
-- Exceptions thrown from product code run with "coverage run" are now displayed
- without internal coverage.py frames, so the output is the same as when the
- code is run without coverage.py.
-
-- Fixed `issue 39`_ and `issue 47`.
-
-.. _issue 39: http://bitbucket.org/ned/coveragepy/issue/39
-.. _issue 40: http://bitbucket.org/ned/coveragepy/issue/40
-.. _issue 47: http://bitbucket.org/ned/coveragepy/issue/47
-
-
-Version 3.2, 5 December 2009
-----------------------------
-
-- Branch coverage: coverage.py can tell you which branches didn't have both (or
- all) choices executed, even where the choice doesn't affect which lines were
- executed. See :ref:`Branch Coverage <branch>` for more details.
-
-- The table of contents in the HTML report is now sortable: click the headers
- on any column. The sorting is persisted so that subsequent reports are
- sorted as you wish. Thanks, `Chris Adams`_.
-
-- XML reporting has file paths that let Cobertura find the source code, fixing
- `issue 21`_.
-
-- The ``--omit`` option now works much better than before, fixing `issue 14`_
- and `issue 33`_. Thanks, Danek Duvall.
-
-- Added a ``--version`` option on the command line.
-
-- Program execution under coverage is a few percent faster.
-
-- Some exceptions reported by the command line interface have been cleaned up
- so that tracebacks inside coverage.py aren't shown. Fixes `issue 23`_.
-
-- Fixed some problems syntax coloring sources with line continuations and
- source with tabs: `issue 30`_ and `issue 31`_.
-
-.. _Chris Adams: http://improbable.org/chris/
-.. _issue 21: http://bitbucket.org/ned/coveragepy/issue/21
-.. _issue 23: http://bitbucket.org/ned/coveragepy/issue/23
-.. _issue 14: http://bitbucket.org/ned/coveragepy/issue/14
-.. _issue 30: http://bitbucket.org/ned/coveragepy/issue/30
-.. _issue 31: http://bitbucket.org/ned/coveragepy/issue/31
-.. _issue 33: http://bitbucket.org/ned/coveragepy/issue/33
-
-
-Version 3.1, 4 October 2009
----------------------------
-
-- Python 3.1 is now supported.
-
-- Coverage.py has a new command line syntax with sub-commands. This expands
- the possibilities for adding features and options in the future. The old
- syntax is still supported. Try ``coverage help`` to see the new commands.
- Thanks to Ben Finney for early help.
-
-- Added an experimental ``coverage xml`` command for producing coverage reports
- in a Cobertura-compatible XML format. Thanks, Bill Hart.
-
-- Added the ``--timid`` option to enable a simpler slower trace function that
- works for DecoratorTools projects, including TurboGears. Fixed `issue 12`_
- and `issue 13`_.
-
-- HTML reports now display syntax-colored Python source.
-
-- Added a ``coverage debug`` command for getting diagnostic information about
- the coverage.py installation.
-
-- Source code can now be read from eggs. Thanks, `Ross Lawley`_. Fixes
- `issue 25`_.
-
-.. _Ross Lawley: http://agileweb.org/
-.. _issue 25: http://bitbucket.org/ned/coveragepy/issue/25
-.. _issue 12: http://bitbucket.org/ned/coveragepy/issue/12
-.. _issue 13: http://bitbucket.org/ned/coveragepy/issue/13
-
-
-Version 3.0.1, 7 July 2009
---------------------------
-
-- Removed the recursion limit in the tracer function. Previously, code that
- ran more than 500 frames deep would crash.
-
-- Fixed a bizarre problem involving pyexpat, whereby lines following XML parser
- invocations could be overlooked.
-
-- On Python 2.3, coverage.py could mis-measure code with exceptions being
- raised. This is now fixed.
-
-- The coverage.py code itself will now not be measured by coverage.py, and no
- coverage modules will be mentioned in the nose ``--with-cover`` plugin.
-
-- When running source files, coverage.py now opens them in universal newline
- mode just like Python does. This lets it run Windows files on Mac, for
- example.
-
-
-Version 3.0, 13 June 2009
--------------------------
-
-- Coverage is now a package rather than a module. Functionality has been split
- into classes.
-
-- HTML reports and annotation of source files: use the new ``-b`` (browser)
- switch. Thanks to George Song for code, inspiration and guidance.
-
-- The trace function is implemented in C for speed. Coverage runs are now
- much faster. Thanks to David Christian for productive micro-sprints and
- other encouragement.
-
-- The minimum supported Python version is 2.3.
-
-- When using the object api (that is, constructing a coverage() object), data
- is no longer saved automatically on process exit. You can re-enable it with
- the ``auto_data=True`` parameter on the coverage() constructor.
- The module-level interface still uses automatic saving.
-
-- Code in the Python standard library is not measured by default. If you need
- to measure standard library code, use the ``-L`` command-line switch during
- execution, or the ``cover_pylib=True`` argument to the coverage()
- constructor.
-
-- API changes:
-
- - Added parameters to coverage.__init__ for options that had been set on
- the coverage object itself.
-
- - Added clear_exclude() and get_exclude_list() methods for programmatic
- manipulation of the exclude regexes.
-
- - Added coverage.load() to read previously-saved data from the data file.
-
- - coverage.annotate_file is no longer available.
-
- - Removed the undocumented cache_file argument to coverage.usecache().
+.. _change: + +==================================== +Major change history for coverage.py +==================================== + +:history: 20090524T134300, brand new docs. +:history: 20090613T164000, final touches for 3.0 +:history: 20090706T205000, changes for 3.0.1 +:history: 20091004T170700, changes for 3.1 +:history: 20091128T072200, changes for 3.2 +:history: 20091205T161525, 3.2 final +:history: 20100221T151900, changes for 3.3 + +These are the major changes for coverage.py. For a more complete change +history, see the `CHANGES.txt`_ file in the source tree. + +.. _CHANGES.txt: http://bitbucket.org/ned/coveragepy/src/tip/CHANGES.txt + + +Version 3.3 +----------- + +- Settings are now read from a .coveragerc file. A specific file can be + specified on the command line with --rcfile=FILE. The name of the file can + be programmatically set with the `config_file` argument to the coverage() + constructor, or reading a config file can be disabled with + `config_file=False`. + +- Added coverage.process_start to enable coverage measurement when Python + starts. + +- Parallel data file names now have a random number appended to them in + addition to the machine name and process id. Also, parallel data files + combined with "coverage combine" are deleted after they're combined, to clean + up unneeded files. Fixes `issue 40`_. + +- Exceptions thrown from product code run with "coverage run" are now displayed + without internal coverage.py frames, so the output is the same as when the + code is run without coverage.py. + +- Fixed `issue 39`_ and `issue 47`. + +.. _issue 39: http://bitbucket.org/ned/coveragepy/issue/39 +.. _issue 40: http://bitbucket.org/ned/coveragepy/issue/40 +.. _issue 47: http://bitbucket.org/ned/coveragepy/issue/47 + + +Version 3.2, 5 December 2009 +---------------------------- + +- Branch coverage: coverage.py can tell you which branches didn't have both (or + all) choices executed, even where the choice doesn't affect which lines were + executed. See :ref:`Branch Coverage <branch>` for more details. + +- The table of contents in the HTML report is now sortable: click the headers + on any column. The sorting is persisted so that subsequent reports are + sorted as you wish. Thanks, `Chris Adams`_. + +- XML reporting has file paths that let Cobertura find the source code, fixing + `issue 21`_. + +- The ``--omit`` option now works much better than before, fixing `issue 14`_ + and `issue 33`_. Thanks, Danek Duvall. + +- Added a ``--version`` option on the command line. + +- Program execution under coverage is a few percent faster. + +- Some exceptions reported by the command line interface have been cleaned up + so that tracebacks inside coverage.py aren't shown. Fixes `issue 23`_. + +- Fixed some problems syntax coloring sources with line continuations and + source with tabs: `issue 30`_ and `issue 31`_. + +.. _Chris Adams: http://improbable.org/chris/ +.. _issue 21: http://bitbucket.org/ned/coveragepy/issue/21 +.. _issue 23: http://bitbucket.org/ned/coveragepy/issue/23 +.. _issue 14: http://bitbucket.org/ned/coveragepy/issue/14 +.. _issue 30: http://bitbucket.org/ned/coveragepy/issue/30 +.. _issue 31: http://bitbucket.org/ned/coveragepy/issue/31 +.. _issue 33: http://bitbucket.org/ned/coveragepy/issue/33 + + +Version 3.1, 4 October 2009 +--------------------------- + +- Python 3.1 is now supported. + +- Coverage.py has a new command line syntax with sub-commands. This expands + the possibilities for adding features and options in the future. The old + syntax is still supported. Try ``coverage help`` to see the new commands. + Thanks to Ben Finney for early help. + +- Added an experimental ``coverage xml`` command for producing coverage reports + in a Cobertura-compatible XML format. Thanks, Bill Hart. + +- Added the ``--timid`` option to enable a simpler slower trace function that + works for DecoratorTools projects, including TurboGears. Fixed `issue 12`_ + and `issue 13`_. + +- HTML reports now display syntax-colored Python source. + +- Added a ``coverage debug`` command for getting diagnostic information about + the coverage.py installation. + +- Source code can now be read from eggs. Thanks, `Ross Lawley`_. Fixes + `issue 25`_. + +.. _Ross Lawley: http://agileweb.org/ +.. _issue 25: http://bitbucket.org/ned/coveragepy/issue/25 +.. _issue 12: http://bitbucket.org/ned/coveragepy/issue/12 +.. _issue 13: http://bitbucket.org/ned/coveragepy/issue/13 + + +Version 3.0.1, 7 July 2009 +-------------------------- + +- Removed the recursion limit in the tracer function. Previously, code that + ran more than 500 frames deep would crash. + +- Fixed a bizarre problem involving pyexpat, whereby lines following XML parser + invocations could be overlooked. + +- On Python 2.3, coverage.py could mis-measure code with exceptions being + raised. This is now fixed. + +- The coverage.py code itself will now not be measured by coverage.py, and no + coverage modules will be mentioned in the nose ``--with-cover`` plugin. + +- When running source files, coverage.py now opens them in universal newline + mode just like Python does. This lets it run Windows files on Mac, for + example. + + +Version 3.0, 13 June 2009 +------------------------- + +- Coverage is now a package rather than a module. Functionality has been split + into classes. + +- HTML reports and annotation of source files: use the new ``-b`` (browser) + switch. Thanks to George Song for code, inspiration and guidance. + +- The trace function is implemented in C for speed. Coverage runs are now + much faster. Thanks to David Christian for productive micro-sprints and + other encouragement. + +- The minimum supported Python version is 2.3. + +- When using the object api (that is, constructing a coverage() object), data + is no longer saved automatically on process exit. You can re-enable it with + the ``auto_data=True`` parameter on the coverage() constructor. + The module-level interface still uses automatic saving. + +- Code in the Python standard library is not measured by default. If you need + to measure standard library code, use the ``-L`` command-line switch during + execution, or the ``cover_pylib=True`` argument to the coverage() + constructor. + +- API changes: + + - Added parameters to coverage.__init__ for options that had been set on + the coverage object itself. + + - Added clear_exclude() and get_exclude_list() methods for programmatic + manipulation of the exclude regexes. + + - Added coverage.load() to read previously-saved data from the data file. + + - coverage.annotate_file is no longer available. + + - Removed the undocumented cache_file argument to coverage.usecache(). diff --git a/doc/index.rst b/doc/index.rst index 7274599e..f179acb5 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,116 +1,116 @@ -===========
-coverage.py
-===========
-
-:history: 20090524T134300, brand new docs.
-:history: 20090613T164000, final touches for 3.0
-:history: 20090618T195900, minor tweaks
-:history: 20090707T205200, changes for 3.0.1
-:history: 20090913T084400, new command line syntax
-:history: 20091004T211900, version 3.1
-:history: 20091127T155100, version 3.2
-:history: 20091205T161429, version 3.2 for real.
-
-
-Coverage.py is a tool for measuring code coverage of Python programs. It
-monitors your program, noting which parts of the code have been executed, then
-analyzes the source to identify code that could have been executed but was not.
-
-Coverage measurement is typically used to gauge the effectiveness of tests. It
-can show which parts of your product code are being exercised by tests, and
-which are not.
-
-The latest version is 3.2, released 5 December 2009.
-It is supported on Python 2.3 through 3.1.
-
-
-Quick start
------------
-
-Getting started is easy:
-
-#. Install coverage.py from the `coverage page on the Python Package Index`__,
- or by using "easy_install coverage". You may need to install the
- python-dev support files, for example with "apt-get install python-dev".
-
-#. Use ``coverage run`` to execute your program and gather data:
-
- .. code-block:: console
-
- $ coverage run my_program.py arg1 arg2
- blah blah ..your program's output.. blah blah
-
-#. Use ``coverage report`` to report on the results:
-
- .. code-block:: console
-
- $ coverage report -m
- Name Stmts Exec Cover Missing
- -------------------------------------------------------
- my_program 20 16 80% 33-35, 39
- my_other_module 56 50 89% 17-23
- -------------------------------------------------------
- TOTAL 76 66 87%
-
-#. For a nicer presentation, use ``coverage html`` to get annotated HTML
- listings detailing missed lines:
-
- .. code-block:: console
-
- $ coverage html
-
- Then visit htmlcov/index.html in your browser, to see a
- `report like this`__.
-
-__ http://pypi.python.org/pypi/coverage
-__ /code/coverage/sample_html/index.html
-
-
-Using coverage.py
------------------
-
-There are a few different ways to use coverage.py. The simplest is the
-:ref:`command line <cmd>`, which lets you run your program and see the results.
-If you need more control over how your project is measured, you can use the
-:ref:`API <api>`.
-
-Some test runners provide coverage integration to make it easy to use coverage
-while running tests. For example, `nose`_ has a `cover plug-in`_.
-
-You can fine-tune coverage's view of your code by directing it to ignore parts
-that you know aren't interesting. See :ref:`Excluding Code <excluding>` for
-details.
-
-.. _nose: http://somethingaboutorange.com/mrl/projects/nose
-.. _cover plug-in: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html
-
-
-History
--------
-
-Coverage.py was originally written by `Gareth Rees`_.
-Since 2004, `Ned Batchelder`_ has extended and maintained it with the help of
-`many others`_.
-
-.. _Gareth Rees: http://garethrees.org/
-.. _Ned Batchelder: http://nedbatchelder.com
-.. _many others: http://bitbucket.org/ned/coveragepy/src/tip/AUTHORS.txt
-
-
-More information
-----------------
-
-.. toctree::
- :maxdepth: 1
-
- cmd
- config
- api
- excluding
- branch
- faq
- changes
-
-
-.. How it works
-.. .coverage file format
+=========== +coverage.py +=========== + +:history: 20090524T134300, brand new docs. +:history: 20090613T164000, final touches for 3.0 +:history: 20090618T195900, minor tweaks +:history: 20090707T205200, changes for 3.0.1 +:history: 20090913T084400, new command line syntax +:history: 20091004T211900, version 3.1 +:history: 20091127T155100, version 3.2 +:history: 20091205T161429, version 3.2 for real. + + +Coverage.py is a tool for measuring code coverage of Python programs. It +monitors your program, noting which parts of the code have been executed, then +analyzes the source to identify code that could have been executed but was not. + +Coverage measurement is typically used to gauge the effectiveness of tests. It +can show which parts of your product code are being exercised by tests, and +which are not. + +The latest version is 3.2, released 5 December 2009. +It is supported on Python 2.3 through 3.1. + + +Quick start +----------- + +Getting started is easy: + +#. Install coverage.py from the `coverage page on the Python Package Index`__, + or by using "easy_install coverage". You may need to install the + python-dev support files, for example with "apt-get install python-dev". + +#. Use ``coverage run`` to execute your program and gather data: + + .. code-block:: console + + $ coverage run my_program.py arg1 arg2 + blah blah ..your program's output.. blah blah + +#. Use ``coverage report`` to report on the results: + + .. code-block:: console + + $ coverage report -m + Name Stmts Exec Cover Missing + ------------------------------------------------------- + my_program 20 16 80% 33-35, 39 + my_other_module 56 50 89% 17-23 + ------------------------------------------------------- + TOTAL 76 66 87% + +#. For a nicer presentation, use ``coverage html`` to get annotated HTML + listings detailing missed lines: + + .. code-block:: console + + $ coverage html + + Then visit htmlcov/index.html in your browser, to see a + `report like this`__. + +__ http://pypi.python.org/pypi/coverage +__ /code/coverage/sample_html/index.html + + +Using coverage.py +----------------- + +There are a few different ways to use coverage.py. The simplest is the +:ref:`command line <cmd>`, which lets you run your program and see the results. +If you need more control over how your project is measured, you can use the +:ref:`API <api>`. + +Some test runners provide coverage integration to make it easy to use coverage +while running tests. For example, `nose`_ has a `cover plug-in`_. + +You can fine-tune coverage's view of your code by directing it to ignore parts +that you know aren't interesting. See :ref:`Excluding Code <excluding>` for +details. + +.. _nose: http://somethingaboutorange.com/mrl/projects/nose +.. _cover plug-in: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html + + +History +------- + +Coverage.py was originally written by `Gareth Rees`_. +Since 2004, `Ned Batchelder`_ has extended and maintained it with the help of +`many others`_. + +.. _Gareth Rees: http://garethrees.org/ +.. _Ned Batchelder: http://nedbatchelder.com +.. _many others: http://bitbucket.org/ned/coveragepy/src/tip/AUTHORS.txt + + +More information +---------------- + +.. toctree:: + :maxdepth: 1 + + cmd + config + api + excluding + branch + faq + changes + + +.. How it works +.. .coverage file format |