Merged pull request #18 manually

8 files changed, 114 insertions, 29 deletions

diff --git a/doc/_ext/px_xlator.py b/doc/_ext/px_xlator.py
index 6085b697..41619119 100644
--- a/doc/_ext/px_xlator.py
+++ b/doc/_ext/px_xlator.py
@@ -1,4 +1,5 @@
 from docutils import nodes
+from sphinx import addnodes
 from sphinx.writers.html import SmartyPantsHTMLTranslator
 from sphinx.builders.html import StandaloneHTMLBuilder
 import os
@@ -10,7 +11,7 @@ def setup(app):
 BaseHtmlXlator = SmartyPantsHTMLTranslator
 class PxTranslator(BaseHtmlXlator):
     """Adjust the HTML translator into a .px translator.
-    
+
     """
 
     def __init__(self, *args, **kwargs):
@@ -45,11 +46,11 @@ class PxTranslator(BaseHtmlXlator):
                 when, what = hist.split(',', 1)
                 self.body.append("<what when='%s'>%s</what>\n" % (when, self.encode(what.strip())))
             self.body.append("</history>\n")
-            
+
         if "b" in self.builder.config.release:
             self.body.append("""
                 <box>
-                These docs are for a beta release, %s. 
+                These docs are for a beta release, %s.
                 For the latest released version, see <a href='/code/coverage'>coverage.py</a>.
                 </box>
                 """ % self.builder.config.release)
@@ -76,8 +77,15 @@ class PxTranslator(BaseHtmlXlator):
         raise nodes.SkipNode
 
     def visit_desc_parameterlist(self, node):
+        # I'm overriding this method so that the base class doesn't write out
+        # <big>(</big>, but I also have to handle the logic from the base class,
+        # so most of this is just copied from sphinx/writers/html.py...
         self.body.append('(')
         self.first_param = 1
+        self.optional_param_level = 0
+        # How many required parameters are left.
+        self.required_params_left = sum([isinstance(c, addnodes.desc_parameter)
+                                         for c in node.children])
         self.param_separator = node.child_text_separator
     def depart_desc_parameterlist(self, node):
         self.body.append(')')
@@ -91,10 +99,10 @@ class PxBuilder(StandaloneHTMLBuilder):
         self.config.html_translator_class = "px_xlator.PxTranslator"
 
         super(PxBuilder, self).init()
-        
+
         self.out_suffix = '.px'
         self.link_suffix = '.html'
-        
+
         if "b" in self.config.release:
             self.px_uri = "/code/coverage/beta/"
         else:
diff --git a/doc/changes.rst b/doc/changes.rst
index 3ddf8896..b9980af8 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -35,6 +35,31 @@ history, see the `CHANGES.txt`_ file in the source tree.
 .. _CHANGES.txt: http://bitbucket.org/ned/coveragepy/src/tip/CHANGES.txt
 
 
+.. _changes_40:
+
+Version 4.0 pre-release --- 27 September 2014
+---------------------------------------------
+
+- Python versions supported are now CPython 2.6, 2.7, 3.2, 3.3, and 3.4, and
+  PyPy 2.2.
+
+- Gevent, eventlet, and greenlet are now supported, closing `issue 149`_.
+  The ``concurrency`` setting specifies the concurrency library in use.  Huge
+  thanks to Peter Portante for initial implementation, and to Joe Jevnik for
+  the final insight that completed the work.
+
+- Options are now also read from a setup.cfg file, if any.  Sections are
+  prefixed with "coverage:", so the ``[run]`` options will be read from the
+  ``[coverage:run]`` section of setup.cfg.  Finishes `issue 304`_.
+
+- The ``report`` command can now show missing branches when reporting on branch
+  coverage.  Thanks, Steve Leonard. Closes `issue 230`_.
+
+.. _issue 149: https://bitbucket.org/ned/coveragepy/issue/149/coverage-gevent-looks-broken
+.. _issue 230: https://bitbucket.org/ned/coveragepy/issue/230/show-line-no-for-missing-branches-in
+.. _issue 304: https://bitbucket.org/ned/coveragepy/issue/304/attempt-to-get-configuration-from-setupcfg
+
+
 .. _changes_371:
 
 Version 3.7.1 --- 13 December 2013
diff --git a/doc/cmd.rst b/doc/cmd.rst
index 49062b31..cd6ae955 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -17,6 +17,7 @@ Coverage command line usage
 :history: 20120807T211600, Clarified the combine rules.
 :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
 
 .. highlight:: console
 
@@ -95,6 +96,16 @@ but before the program invocation::
     $ coverage run --source=dir1,dir2 my_program.py arg1 arg2
     $ coverage run --source=dir1,dir2 -m packagename.modulename arg1 arg2
 
+Coverage can measure multi-threaded programs by default. If you are using
+more exotic concurrency, with the `greenlet`_, `eventlet`_, or `gevent`_
+libraries, then coverage will get very confused.  Use the ``--concurrency``
+switch to properly measure programs using these libraries.  Give it a value of
+``greenlet``, ``eventlet``, or ``gevent``.
+
+.. _greenlet: http://greenlet.readthedocs.org/en/latest/
+.. _gevent: http://www.gevent.org/
+.. _eventlet: http://eventlet.net/
+
 By default, coverage does not measure code installed with the Python
 interpreter, for example, the standard library. If you want to measure that
 code as well as your own, add the ``-L`` flag.
@@ -102,9 +113,7 @@ code as well as your own, add the ``-L`` flag.
 If your coverage results seem to be overlooking code that you know has been
 executed, try running coverage again with the ``--timid`` flag.  This uses a
 simpler but slower trace method.  Projects that use DecoratorTools, including
-TurboGears, will need to use ``--timid`` to get correct results.  This option
-can also be enabled by setting the environment variable COVERAGE_OPTIONS to
-``--timid``.
+TurboGears, will need to use ``--timid`` to get correct results.
 
 If you are measuring coverage in a multi-process program, or across a number of
 machines, you'll want the ``--parallel-mode`` switch to keep the data separate
@@ -266,6 +275,19 @@ The ``-m`` flag also shows the line numbers of missing statements::
     -------------------------------------------------------
     TOTAL                        91     12    87%
 
+If you are using branch coverage, then branch statistics will be reported in
+the Branch and BrMiss columns, the Missing column will detail the missed
+branches::
+
+    $ coverage report -m
+    Name                      Stmts   Miss Branch BrMiss  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
+    ---------------------------------------------------------------------
+    TOTAL                        91     12     18      3    87%
+
 You can restrict the report to only certain files by naming them on the
 command line::
 
diff --git a/doc/conf.py b/doc/conf.py
index 41a00e3e..16f566f0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -40,16 +40,16 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'coverage.py'
-copyright = u'2009\N{EN DASH}2013, Ned Batchelder'
+copyright = u'2009\N{EN DASH}2014, Ned Batchelder'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '3.7.1'
+version = '4.0'
 # The full version, including alpha/beta/rc tags.
-release = '3.7.1'
+release = '4.0a1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/config.rst b/doc/config.rst
index 882fc777..cec14e0f 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -10,6 +10,7 @@ Configuration files
 :history: 20110604T184400, updated for 3.5.
 :history: 20110827T212700, updated for 3.5.1
 :history: 20130926T222300, updated for 3.6.1
+:history: 20140925T064700, updated for 4.0a1
 
 
 Coverage.py options can be specified in a configuration file.  This makes it
@@ -26,6 +27,14 @@ configuration file are tied to your source code and how it should be measured,
 so it should be stored with your source, and checked into source control,
 rather than put in your home directory.
 
+A different name for the configuration file can be specified with the
+``--rcfile=FILE`` command line option.
+
+Coverage.py will read settings from a ``setup.cfg`` file if no other
+configuration file is used.  In this case, the section names have "coverage:"
+prefixed, so the ``[run]`` options described below will be found in the
+``[coverage:run]`` section of ``setup.cfg``.
+
 
 Syntax
 ------
@@ -90,6 +99,15 @@ 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 will produce very wrong results.
+
+.. _greenlet: http://greenlet.readthedocs.org/en/latest/
+.. _gevent: http://www.gevent.org/
+.. _eventlet: http://eventlet.net/
+
 ``data_file`` (string, default ".coverage"): the name of the data file to use
 for storing or reporting coverage.
 
diff --git a/doc/index.rst b/doc/index.rst
index 3a0d9308..d557665c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -31,6 +31,7 @@ coverage.py
 :history: 20130105T174000, Updated for 3.6
 :history: 20131005T210000, Updated for 3.7
 :history: 20131212T213300, Updated for 3.7.1
+:history: 20140924T073000, Updated for 4.0a1
 
 
 Coverage.py is a tool for measuring code coverage of Python programs. It
@@ -44,14 +45,14 @@ not.
 .. ifconfig:: not prerelease
 
     The latest version is coverage.py 3.7.1, released 13 December 2013.
-    It is supported on Python versions 2.3 through 3.4, and PyPy 2.1.
+    It is supported on Python versions 2.6 through 3.4, and PyPy 2.2.
 
 .. ifconfig:: prerelease
 
-    The latest version is coverage.py 3.6b3, released 29 December 2012.
-    It is supported on Python versions 2.3 through 3.3, and PyPy 1.9.
+    The latest version is coverage.py 4.0a1, released 27 September 2014.
+    It is supported on Python versions 2.6 through 3.4, and PyPy 2.2 through 2.4.
     **This is a pre-release build.  The usual warnings about possible bugs apply.**
-    The latest stable version is coverage.py 3.5.3, `described here`_.
+    The latest stable version is coverage.py 3.7.1, `described here`_.
 
 .. _described here: http://nedbatchelder.com/code/coverage
 
diff --git a/doc/install.rst b/doc/install.rst
index bc8097a2..7dfa5668 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -20,29 +20,36 @@ Installation
 :history: 20130105T174400, updated for 3.6.
 :history: 20131005T210600, updated for 3.7.
 :history: 20131212T213500, updated for 3.7.1.
+:history: 20140927T102700, updated for 4.0a1.
 
 
 .. highlight:: console
+
 .. _coverage_pypi: http://pypi.python.org/pypi/coverage
 .. _setuptools: http://pypi.python.org/pypi/setuptools
 .. _Distribute: http://packages.python.org/distribute/
 
 
-Installing coverage.py is done in the usual ways. You must have `setuptools`_
-or `Distribute`_ installed already, and then you:
+Installing coverage.py is done in the usual ways. The simplest way is with
+pip::
 
-#.  Download the appropriate kit from the
-    `coverage page on the Python Package Index`__.
+    $ pip install coverage
 
-#.  Run ``python setup.py install``.
+.. ifconfig:: prerelease
 
-or, use::
+    To install a pre-release version, you will need to specify ``--pre``::
 
-    $ pip install coverage
+        $ pip install --pre coverage
 
-or even::
 
-    $ easy_install coverage
+The alternate old-school technique is:
+
+#.  Install (or already have installed) `setuptools`_ or `Distribute`_.
+
+#.  Download the appropriate kit from the
+    `coverage page on the Python Package Index`__.
+
+#.  Run ``python setup.py install``.
 
 .. __: coverage_pypi_
 
@@ -75,9 +82,9 @@ If all went well, you should be able to open a command prompt, and see coverage
 installed properly::
 
     $ coverage --version
-    Coverage.py, version 3.7.1.  http://nedbatchelder.com/code/coverage
+    Coverage.py, version 4.0a1.  http://nedbatchelder.com/code/coverage
 
 You can also invoke coverage as a module::
 
     $ python -m coverage --version
-    Coverage.py, version 3.7.1.  http://nedbatchelder.com/code/coverage
+    Coverage.py, version 4.0a1.  http://nedbatchelder.com/code/coverage
diff --git a/doc/python-coverage.1.txt b/doc/python-coverage.1.txt
index 89c70b53..f79f33d8 100644
--- a/doc/python-coverage.1.txt
+++ b/doc/python-coverage.1.txt
@@ -8,7 +8,7 @@ measure code coverage of Python program execution
 
 :Author: Ned Batchelder <ned@nedbatchelder.com>
 :Author: |author|
-:Date: 2013-10-10
+:Date: 2014-09-27
 :Copyright: BSD license, attribution and disclaimer required.
 :Manual section: 1
 :Manual group: Coverage
@@ -76,8 +76,8 @@ GLOBAL OPTIONS
     Usually needs quoting on the command line.
 
 **--include** `PATTERN` [ , ... ]
-    Include files only when their filename path matches one of these
-    PATTERNs. Usually needs quoting on the command line.
+    Include only files whose paths match one of these
+    PATTERNs. Accepts shell-style wildcards, which must be quoted.
 
 
 COMMAND REFERENCE
@@ -160,6 +160,10 @@ COMMAND REFERENCE
     \--branch
         Measure branch coverage in addition to statement coverage.
 
+    \--concurrency `LIB`
+        Properly measure code using a concurrency library. Valid values are:
+        thread, gevent, greenlet, eventlet.
+
     \--debug `DEBUGOPT`,...
         Debug options `DEBUGOPT`, separated by commas.