diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api_coverage.rst | 2 | ||||
| -rw-r--r-- | doc/api_coveragedata.rst | 4 | ||||
| -rw-r--r-- | doc/changes.rst | 12 | ||||
| -rw-r--r-- | doc/cmd.rst | 118 | ||||
| -rw-r--r-- | doc/config.rst | 28 | ||||
| -rw-r--r-- | doc/index.rst | 4 | ||||
| -rw-r--r-- | doc/plugins.rst | 4 |
7 files changed, 115 insertions, 57 deletions
diff --git a/doc/api_coverage.rst b/doc/api_coverage.rst index 69b64c3..153ca2c 100644 --- a/doc/api_coverage.rst +++ b/doc/api_coverage.rst @@ -3,6 +3,8 @@ .. _api_coverage: +.. :history: 20150802T174800, new file for 4.0b1 + The Coverage class ------------------ diff --git a/doc/api_coveragedata.rst b/doc/api_coveragedata.rst index dec505c..9b88bb7 100644 --- a/doc/api_coveragedata.rst +++ b/doc/api_coveragedata.rst @@ -3,9 +3,13 @@ .. _api_coveragedata: +.. :history: 20150802T174800, new doc for 4.0b1 + The CoverageData class ---------------------- +.. versionadded:: 4.0 + .. autoclass:: coverage.CoverageData :members: :special-members: __init__ diff --git a/doc/changes.rst b/doc/changes.rst index 4a64c05..db71d69 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -31,6 +31,8 @@ Major change history for coverage.py .. :history: 20131005T205700, updated for 3.7 .. :history: 20131212T213100, updated for 3.7.1 .. :history: 20150124T134800, updated for 4.0a4 +.. :history: 20150902T174700, updated for 4.0b1 + These are the major changes for coverage.py. For a more complete change history, see the `CHANGES.txt`_ file in the source tree. @@ -46,7 +48,7 @@ Version 4.0b1 pre-release --- 2 August 2015 Backward incompatibilities: -- CPython versions supported are now Python 2.6, 2.7, 3.3, 3.4 and 3.5b2. +- CPython versions supported are now Python 2.6, 2.7, 3.3, 3.4 and 3.5b4. PyPy2 2.4, 2.6, and PyPy3 2.4 are also supported. - The original command line switches (`-x` to run a program, etc) are no @@ -102,10 +104,10 @@ New features: prefixed with "coverage:", so the ``[run]`` options will be read from the ``[coverage:run]`` section of setup.cfg. Finishes `issue 304`_. -- A new option: `coverage report --skip-covered` will reduce the number of - files reported by skipping files with 100% coverage. Thanks, Krystian - Kichewko. This means that empty `__init__.py` files will be skipped, since - they are 100% covered, closing `issue 315`_. +- A new option: `coverage report --skip-covered` (or ``[report] skip_covered``) + will reduce the number of files reported by skipping files with 100% + coverage. Thanks, Krystian Kichewko. This means that empty `__init__.py` + files will be skipped, since they are 100% covered, closing `issue 315`_. - You can now specify the ``--fail-under`` option in the ``.coveragerc`` file as the ``[report] fail_under`` options. This closes `issue 314`_. diff --git a/doc/cmd.rst b/doc/cmd.rst index 7827a5e..b1440bb 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -21,6 +21,7 @@ Coverage.py command line usage .. :history: 20121003T074600, Fixed an option reference, https://bitbucket.org/ned/coveragepy/issue/200/documentation-mentions-output-xml-instead .. :history: 20121117T091000, Added command aliases. .. :history: 20140924T193000, Added --concurrency +.. :history: 20150802T174700, Updated for 4.0b1 .. highlight:: console @@ -100,11 +101,12 @@ but before the program invocation:: $ coverage run --source=dir1,dir2 -m packagename.modulename arg1 arg2 Coverage.py can measure multi-threaded programs by default. If you are using -more exotic concurrency, with the `greenlet`_, `eventlet`_, or `gevent`_ -libraries, then coverage.py will get very confused. Use the ``--concurrency`` -switch to properly measure programs using these libraries. Give it a value of -``greenlet``, ``eventlet``, or ``gevent``. +more exotic concurrency, with the `multiprocessing`_, `greenlet`_, `eventlet`_, +or `gevent`_ libraries, then coverage.py will get very confused. Use the +``--concurrency`` switch to properly measure programs using these libraries. +Give it a value of ``greenlet``, ``eventlet``, or ``gevent``. +.. _multiprocessing: https://docs.python.org/2/library/multiprocessing.html .. _greenlet: http://greenlet.readthedocs.org/en/latest/ .. _gevent: http://www.gevent.org/ .. _eventlet: http://eventlet.net/ @@ -150,24 +152,11 @@ could affect the measurement process. The possible warnings include: This could be because you asked to measure only modules that never ran, or for other reasons. -.. _cmd_run_debug: - -The ``--debug`` option instructs coverage.py to log internal details of its -operation, to help with diagnosing problems. It takes a comma-separated list -of options, each indicating a facet of operation to log to stderr: - -* ``trace``: print every decision about whether to trace a file or not. For - files not being traced, the reason is also given. - -* ``config``: before starting, dump all the :ref:`configuration <config>` - values. +* "Module XXX was previously imported, but not measured." -* ``sys``: before starting, dump all the system and environment information, - as with :ref:`coverage debug sys <cmd_debug>`. - -* ``dataio``: log when reading or writing any data file. - -* ``pid``: annotate all debug output with the process id. + You asked coverage.py to measure module XXX, but it had already been imported + when coverage started. This meant coverage.py couldn't monitor its + execution. .. _cmd_datafile: @@ -194,9 +183,7 @@ Combining data files -------------------- If you need to collect coverage data from different machines or processes, -coverage.py can combine multiple files into one for reporting. Use the ``-p`` -flag during execution to append distinguishing information to the .coverage -data file name. +coverage.py can combine multiple files into one for reporting. Once you have created a number of these files, you can copy them all to a single directory, and use the **combine** command to combine them into one @@ -204,21 +191,35 @@ single directory, and use the **combine** command to combine them into one $ coverage combine -If the different machines run your code from different places in their file -systems, coverage.py won't know how to combine the data. You can tell -coverage.py how the different locations correlate with a ``[paths]`` section in -your configuration file. See :ref:`config_paths` for details. +You can also name directories or files on the command line:: -If you are collecting and renaming your own data files, you'll need to name -them properly for **combine** to find them. It looks for files named after -the data file (defaulting to ".coverage", overridable with COVERAGE_FILE), with -a dotted suffix. All such files in the current directory will be combined. -Here are some examples of data files that can be combined:: + $ combine combine data1.dat windows_data_files/ + +Coverage.py will collect the data from those places and combine them. The +current directory isn't searched if you use command-line arguments. If you +also want data from the current directory, name it explicitly on the command +line. + +When coverage.py looks in directories for data files to combine, even the +current directory, it only reads files with certain names. It looks for files +named the same as the data file (defaulting to ".coverage"), with a dotted +suffix. Here are some examples of data files that can be combined:: .coverage.machine1 .coverage.20120807T212300 .coverage.last_good_run.ok +The ``run --parallel-mode`` switch automatically creates separate data files +for each run which can be combined later. The file names include the machine +name, the process id, and a random number:: + + .coverage.Neds-MacBook-Pro.local.88335.316857 + .coverage.Geometer.8044.799674 + +If the different machines run your code from different places in their file +systems, coverage.py won't know how to combine the data. You can tell +coverage.py how the different locations correlate with a ``[paths]`` section in +your configuration file. See :ref:`config_paths` for details. .. _cmd_reporting: @@ -257,9 +258,9 @@ The simplest reporting is a textual summary produced with **report**:: $ coverage report Name Stmts Miss Cover --------------------------------------------- - my_program 20 4 80% - my_module 15 2 86% - my_other_module 56 6 89% + my_program.py 20 4 80% + my_module.py 15 2 86% + my_other_module.py 56 6 89% --------------------------------------------- TOTAL 91 12 87% @@ -272,9 +273,9 @@ The ``-m`` flag also shows the line numbers of missing statements:: $ coverage report -m Name Stmts Miss Cover Missing ------------------------------------------------------- - my_program 20 4 80% 33-35, 39 - my_module 15 2 86% 8, 12 - my_other_module 56 6 89% 17-23 + my_program.py 20 4 80% 33-35, 39 + my_module.py 15 2 86% 8, 12 + my_other_module.py 56 6 89% 17-23 ------------------------------------------------------- TOTAL 91 12 87% @@ -285,9 +286,9 @@ detail the missed branches:: $ coverage report -m Name Stmts Miss Branch BrPart Cover Missing --------------------------------------------------------------------- - my_program 20 4 10 2 80% 33-35, 36->38, 39 - my_module 15 2 3 0 86% 8, 12 - my_other_module 56 6 5 1 89% 17-23, 40->45 + my_program.py 20 4 10 2 80% 33-35, 36->38, 39 + my_module.py 15 2 3 0 86% 8, 12 + my_other_module.py 56 6 5 1 89% 17-23, 40->45 --------------------------------------------------------------------- TOTAL 91 12 18 3 87% @@ -297,11 +298,14 @@ command line:: $ coverage report -m my_program.py my_other_module.py Name Stmts Miss Cover Missing ------------------------------------------------------- - my_program 20 4 80% 33-35, 39 - my_other_module 56 6 89% 17-23 + my_program.py 20 4 80% 33-35, 39 + my_other_module.py 56 6 89% 17-23 ------------------------------------------------------- TOTAL 76 10 87% +The ``--skip-covered`` switch will leave out any file with 100% coverage, +letting you focus on the files that still need attention. + Other common reporting options are described above in :ref:`cmd_reporting`. @@ -406,3 +410,29 @@ command can often help:: Two types of information are available: ``sys`` to show system configuration, and ``data`` to show a summary of the collected coverage data. + + +.. _cmd_run_debug: + +The ``--debug`` option is available on all commands. It instructs coverage.py +to log internal details of its operation, to help with diagnosing problems. It +takes a comma-separated list of options, each indicating a facet of operation +to log to stderr: + +* ``trace``: print every decision about whether to trace a file or not. For + files not being traced, the reason is also given. + +* ``config``: before starting, dump all the :ref:`configuration <config>` + values. + +* ``sys``: before starting, dump all the system and environment information, + as with :ref:`coverage debug sys <cmd_debug>`. + +* ``dataio``: log when reading or writing any data file. + +* ``pid``: annotate all debug output with the process id. + +* ``plugin``: print information about plugin operations. + +Debug options can also be set with the ``COVERAGE_DEBUG`` environment variable, +a comma-separated list of these options. diff --git a/doc/config.rst b/doc/config.rst index 980d046..85e1533 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -15,6 +15,7 @@ Configuration files .. :history: 20130926T222300, updated for 3.6.1 .. :history: 20140925T064700, updated for 4.0a1 .. :history: 20150124T173400, updated for 4.0a4 +.. :history: 20150802T174600, updated for 4.0b1 Coverage.py options can be specified in a configuration file. This makes it @@ -105,15 +106,18 @@ to more than one command. ``cover_pylib`` (boolean, default False): whether to measure the Python standard library. -``concurrency`` (string, default "thread"): the name of the concurrency -library in use by the product code. If your program uses `gevent`_, -`greenlet`_, or `eventlet`_, you must name that library in this option, or -coverage.py will produce very wrong results. +``concurrency`` (string, default "thread"): the name of the concurrency library +in use by the product code. If your program uses `multiprocessing`_, +`gevent`_, `greenlet`_, or `eventlet`_, you must name that library in this +option, or coverage.py will produce very wrong results. +.. _multiprocessing: https://docs.python.org/2/library/multiprocessing.html .. _greenlet: http://greenlet.readthedocs.org/en/latest/ .. _gevent: http://www.gevent.org/ .. _eventlet: http://eventlet.net/ +.. versionadded:: 4.0 + ``data_file`` (string, default ".coverage"): the name of the data file to use for storing or reporting coverage. @@ -123,6 +127,10 @@ for storing or reporting coverage. ``include`` (multi-string): a list of filename patterns, the files to include in measurement or reporting. See :ref:`source` for details. +``note`` (string): an arbitrary string that will be written to the data file. +You can use the :meth:`CoverageData.run_infos` method to retrieve this string +from a data file. + ``omit`` (multi-string): a list of filename patterns, the files to leave out of measurement or reporting. See :ref:`source` for details. @@ -180,6 +188,9 @@ reported as missing. More details are in :ref:`excluding`. If you use this option, you are replacing all the exclude regexes, so you'll need to also supply the "pragma: no cover" regex if you still want to use it. +``fail_under`` (integer): a target coverage percentage. If the total coverage +measurement is under this value, then exit with a status code of 2. + ``ignore_errors`` (boolean, default False): ignore source code that can't be found. @@ -202,8 +213,8 @@ example "87%". A value of 2 will display percentages like "87.32%". ``show_missing`` (boolean, default False): when running a summary report, show missing lines. See :ref:`cmd_summary` for more information. -``skip_covered`` (boolean, default False): when running a summary report, -skip 100% covered files. See :ref:`cmd_summary` for more information. +``skip_covered`` (boolean, default False): Don't include files in the report +that are 100% covered files. See :ref:`cmd_summary` for more information. .. _config_html: @@ -234,3 +245,8 @@ Values particular to XML reporting. The values in the ``[report]`` section also apply to XML output, where appropriate. ``output`` (string, default "coverage.xml"): where to write the XML report. + +``package_depth`` (integer, default 99): controls which directories are +identified as packages in the report. Directories deeper than this depth are +not reported as packages. The default is that all directories are reported as +packages. diff --git a/doc/index.rst b/doc/index.rst index 904734f..fef9af7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -87,8 +87,8 @@ Getting started is easy: $ coverage report -m Name Stmts Miss Cover Missing ------------------------------------------------------- - my_program 20 4 80% 33-35, 39 - my_other_module 56 6 89% 17-23 + my_program.py 20 4 80% 33-35, 39 + my_other_module.py 56 6 89% 17-23 ------------------------------------------------------- TOTAL 76 10 87% diff --git a/doc/plugins.rst b/doc/plugins.rst index 30d7339..a7c911a 100644 --- a/doc/plugins.rst +++ b/doc/plugins.rst @@ -8,6 +8,10 @@ Plugins ======= .. :history: 20150124T143000, new page. +.. :history: 20150802T174600, updated for 4.0b1 + + +.. versionadded:: 4.0 Coverage.py's behavior can be extended by writing plugins. A plugin is a separately installed Python class that you register in your .coveragerc. |