third_party/pycoverage/coverage/__init__.py

   1 """Code coverage measurement for Python.
   2
   3 Ned Batchelder
   4 http://nedbatchelder.com/code/coverage
   5
   6 """
   7
   8 from coverage.version import __version__, __url__
   9
  10 from coverage.control import coverage, process_startup
  11 from coverage.data import CoverageData
  12 from coverage.cmdline import main, CoverageScript
  13 from coverage.misc import CoverageException
  14
  15 # Module-level functions.  The original API to this module was based on
  16 # functions defined directly in the module, with a singleton of the coverage()
  17 # class.  That design hampered programmability, so the current api uses
  18 # explicitly-created coverage objects.  But for backward compatibility, here we
  19 # define the top-level functions to create the singleton when they are first
  20 # called.
  21
  22 # Singleton object for use with module-level functions.  The singleton is
  23 # created as needed when one of the module-level functions is called.
  24 _the_coverage = None
  25
  26 def _singleton_method(name):
  27     """Return a function to the `name` method on a singleton `coverage` object.
  28
  29     The singleton object is created the first time one of these functions is
  30     called.
  31
  32     """
  33     # Disable pylint msg W0612, because a bunch of variables look unused, but
  34     # they're accessed via locals().
  35     # pylint: disable=W0612
  36
  37     def wrapper(*args, **kwargs):
  38         """Singleton wrapper around a coverage method."""
  39         global _the_coverage
  40         if not _the_coverage:
  41             _the_coverage = coverage(auto_data=True)
  42         return getattr(_the_coverage, name)(*args, **kwargs)
  43
  44     import inspect
  45     meth = getattr(coverage, name)
  46     args, varargs, kw, defaults = inspect.getargspec(meth)
  47     argspec = inspect.formatargspec(args[1:], varargs, kw, defaults)
  48     docstring = meth.__doc__
  49     wrapper.__doc__ = ("""\
  50         A first-use-singleton wrapper around coverage.%(name)s.
  51
  52         This wrapper is provided for backward compatibility with legacy code.
  53         New code should use coverage.%(name)s directly.
  54
  55         %(name)s%(argspec)s:
  56
  57         %(docstring)s
  58         """ % locals()
  59         )
  60
  61     return wrapper
  62
  63
  64 # Define the module-level functions.
  65 use_cache = _singleton_method('use_cache')
  66 start =     _singleton_method('start')
  67 stop =      _singleton_method('stop')
  68 erase =     _singleton_method('erase')
  69 exclude =   _singleton_method('exclude')
  70 analysis =  _singleton_method('analysis')
  71 analysis2 = _singleton_method('analysis2')
  72 report =    _singleton_method('report')
  73 annotate =  _singleton_method('annotate')
  74
  75
  76 # On Windows, we encode and decode deep enough that something goes wrong and
  77 # the encodings.utf_8 module is loaded and then unloaded, I don't know why.
  78 # Adding a reference here prevents it from being unloaded.  Yuk.
  79 import encodings.utf_8
  80
  81 # Because of the "from coverage.control import fooey" lines at the top of the
  82 # file, there's an entry for coverage.coverage in sys.modules, mapped to None.
  83 # This makes some inspection tools (like pydoc) unable to find the class
  84 # coverage.coverage.  So remove that entry.
  85 import sys
  86 try:
  87     del sys.modules['coverage.coverage']
  88 except KeyError:
  89     pass
  90
  91
  92 # COPYRIGHT AND LICENSE
  93 #
  94 # Copyright 2001 Gareth Rees.  All rights reserved.
  95 # Copyright 2004-2013 Ned Batchelder.  All rights reserved.
  96 #
  97 # Redistribution and use in source and binary forms, with or without
  98 # modification, are permitted provided that the following conditions are
  99 # met:
 100 #
 101 # 1. Redistributions of source code must retain the above copyright
 102 #    notice, this list of conditions and the following disclaimer.
 103 #
 104 # 2. Redistributions in binary form must reproduce the above copyright
 105 #    notice, this list of conditions and the following disclaimer in the
 106 #    documentation and/or other materials provided with the
 107 #    distribution.
 108 #
 109 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 110 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 111 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 112 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 113 # HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 114 # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 115 # BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 116 # OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 117 # ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 118 # TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 119 # USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 120 # DAMAGE.