contrib/coverage.py

   1 #!/usr/bin/python
   2 #
   3 #             Perforce Defect Tracking Integration Project
   4 #              <http://www.ravenbrook.com/project/p4dti/>
   5 #
   6 #                   COVERAGE.PY -- COVERAGE TESTING
   7 #
   8 #             Gareth Rees, Ravenbrook Limited, 2001-12-04
   9 #                     Ned Batchelder, 2004-12-12
  10 #         http://nedbatchelder.com/code/modules/coverage.html
  11 #
  12 #
  13 # 1. INTRODUCTION
  14 #
  15 # This module provides coverage testing for Python code.
  16 #
  17 # The intended readership is all Python developers.
  18 #
  19 # This document is not confidential.
  20 #
  21 # See [GDR 2001-12-04a] for the command-line interface, programmatic
  22 # interface and limitations.  See [GDR 2001-12-04b] for requirements and
  23 # design.
  24
  25 import pdb
  26
  27 r"""Usage:
  28
  29 coverage.py -x [-p] MODULE.py [ARG1 ARG2 ...]
  30     Execute module, passing the given command-line arguments, collecting
  31     coverage data. With the -p option, write to a temporary file containing
  32     the machine name and process ID.
  33
  34 coverage.py -e
  35     Erase collected coverage data.
  36
  37 coverage.py -c
  38     Collect data from multiple coverage files (as created by -p option above)
  39     and store it into a single file representing the union of the coverage.
  40
  41 coverage.py -r [-m] [-o dir1,dir2,...] FILE1 FILE2 ...
  42     Report on the statement coverage for the given files.  With the -m
  43     option, show line numbers of the statements that weren't executed.
  44
  45 coverage.py -a [-d dir] [-o dir1,dir2,...] FILE1 FILE2 ...
  46     Make annotated copies of the given files, marking statements that
  47     are executed with > and statements that are missed with !.  With
  48     the -d option, make the copies in that directory.  Without the -d
  49     option, make each copy in the same directory as the original.
  50
  51 -o dir,dir2,...
  52   Omit reporting or annotating files when their filename path starts with
  53   a directory listed in the omit list.
  54   e.g. python coverage.py -i -r -o c:\python23,lib\enthought\traits
  55
  56 Coverage data is saved in the file .coverage by default.  Set the
  57 COVERAGE_FILE environment variable to save it somewhere else."""
  58
  59 __version__ = "2.78.20070930"    # see detailed history at the end of this file.
  60
  61 import compiler
  62 import compiler.visitor
  63 import glob
  64 import os
  65 import re
  66 import string
  67 import symbol
  68 import sys
  69 import threading
  70 import token
  71 import types
  72 from socket import gethostname
  73
  74 # Python version compatibility
  75 try:
  76     strclass = basestring   # new to 2.3
  77 except:
  78     strclass = str
  79
  80 # 2. IMPLEMENTATION
  81 #
  82 # This uses the "singleton" pattern.
  83 #
  84 # The word "morf" means a module object (from which the source file can
  85 # be deduced by suitable manipulation of the __file__ attribute) or a
  86 # filename.
  87 #
  88 # When we generate a coverage report we have to canonicalize every
  89 # filename in the coverage dictionary just in case it refers to the
  90 # module we are reporting on.  It seems a shame to throw away this
  91 # information so the data in the coverage dictionary is transferred to
  92 # the 'cexecuted' dictionary under the canonical filenames.
  93 #
  94 # The coverage dictionary is called "c" and the trace function "t".  The
  95 # reason for these short names is that Python looks up variables by name
  96 # at runtime and so execution time depends on the length of variables!
  97 # In the bottleneck of this application it's appropriate to abbreviate
  98 # names to increase speed.
  99
 100 class StatementFindingAstVisitor(compiler.visitor.ASTVisitor):
 101     """ A visitor for a parsed Abstract Syntax Tree which finds executable
 102         statements.
 103     """
 104     def __init__(self, statements, excluded, suite_spots):
 105         compiler.visitor.ASTVisitor.__init__(self)
 106         self.statements = statements
 107         self.excluded = excluded
 108         self.suite_spots = suite_spots
 109         self.excluding_suite = 0
 110
 111     def doRecursive(self, node):
 112         for n in node.getChildNodes():
 113             self.dispatch(n)
 114
 115     visitStmt = visitModule = doRecursive
 116
 117     def doCode(self, node):
 118         if hasattr(node, 'decorators') and node.decorators:
 119             self.dispatch(node.decorators)
 120             self.recordAndDispatch(node.code)
 121         else:
 122             self.doSuite(node, node.code)
 123
 124     visitFunction = visitClass = doCode
 125
 126     def getFirstLine(self, node):
 127         # Find the first line in the tree node.
 128         lineno = node.lineno
 129         for n in node.getChildNodes():
 130             f = self.getFirstLine(n)
 131             if lineno and f:
 132                 lineno = min(lineno, f)
 133             else:
 134                 lineno = lineno or f
 135         return lineno
 136
 137     def getLastLine(self, node):
 138         # Find the first line in the tree node.
 139         lineno = node.lineno
 140         for n in node.getChildNodes():
 141             lineno = max(lineno, self.getLastLine(n))
 142         return lineno
 143
 144     def doStatement(self, node):
 145         self.recordLine(self.getFirstLine(node))
 146
 147     visitAssert = visitAssign = visitAssTuple = visitPrint = \
 148         visitPrintnl = visitRaise = visitSubscript = visitDecorators = \
 149         doStatement
 150
 151     def visitPass(self, node):
 152         # Pass statements have weird interactions with docstrings.  If this
 153         # pass statement is part of one of those pairs, claim that the statement
 154         # is on the later of the two lines.
 155         l = node.lineno
 156         if l:
 157             lines = self.suite_spots.get(l, [l,l])
 158             self.statements[lines[1]] = 1
 159
 160     def visitDiscard(self, node):
 161         # Discard nodes are statements that execute an expression, but then
 162         # discard the results.  This includes function calls, so we can't
 163         # ignore them all.  But if the expression is a constant, the statement
 164         # won't be "executed", so don't count it now.
 165         if node.expr.__class__.__name__ != 'Const':
 166             self.doStatement(node)
 167
 168     def recordNodeLine(self, node):
 169         # Stmt nodes often have None, but shouldn't claim the first line of
 170         # their children (because the first child might be an ignorable line
 171         # like "global a").
 172         if node.__class__.__name__ != 'Stmt':
 173             return self.recordLine(self.getFirstLine(node))
 174         else:
 175             return 0
 176
 177     def recordLine(self, lineno):
 178         # Returns a bool, whether the line is included or excluded.
 179         if lineno:
 180             # Multi-line tests introducing suites have to get charged to their
 181             # keyword.
 182             if lineno in self.suite_spots:
 183                 lineno = self.suite_spots[lineno][0]
 184             # If we're inside an excluded suite, record that this line was
 185             # excluded.
 186             if self.excluding_suite:
 187                 self.excluded[lineno] = 1
 188                 return 0
 189             # If this line is excluded, or suite_spots maps this line to
 190             # another line that is exlcuded, then we're excluded.
 191             elif self.excluded.has_key(lineno) or \
 192                  self.suite_spots.has_key(lineno) and \
 193                  self.excluded.has_key(self.suite_spots[lineno][1]):
 194                 return 0
 195             # Otherwise, this is an executable line.
 196             else:
 197                 self.statements[lineno] = 1
 198                 return 1
 199         return 0
 200
 201     default = recordNodeLine
 202
 203     def recordAndDispatch(self, node):
 204         self.recordNodeLine(node)
 205         self.dispatch(node)
 206
 207     def doSuite(self, intro, body, exclude=0):
 208         exsuite = self.excluding_suite
 209         if exclude or (intro and not self.recordNodeLine(intro)):
 210             self.excluding_suite = 1
 211         self.recordAndDispatch(body)
 212         self.excluding_suite = exsuite
 213
 214     def doPlainWordSuite(self, prevsuite, suite):
 215         # Finding the exclude lines for else's is tricky, because they aren't
 216         # present in the compiler parse tree.  Look at the previous suite,
 217         # and find its last line.  If any line between there and the else's
 218         # first line are excluded, then we exclude the else.
 219         lastprev = self.getLastLine(prevsuite)
 220         firstelse = self.getFirstLine(suite)
 221         for l in range(lastprev+1, firstelse):
 222             if self.suite_spots.has_key(l):
 223                 self.doSuite(None, suite, exclude=self.excluded.has_key(l))
 224                 break
 225         else:
 226             self.doSuite(None, suite)
 227
 228     def doElse(self, prevsuite, node):
 229         if node.else_:
 230             self.doPlainWordSuite(prevsuite, node.else_)
 231
 232     def visitFor(self, node):
 233         self.doSuite(node, node.body)
 234         self.doElse(node.body, node)
 235
 236     visitWhile = visitFor
 237
 238     def visitIf(self, node):
 239         # The first test has to be handled separately from the rest.
 240         # The first test is credited to the line with the "if", but the others
 241         # are credited to the line with the test for the elif.
 242         self.doSuite(node, node.tests[0][1])
 243         for t, n in node.tests[1:]:
 244             self.doSuite(t, n)
 245         self.doElse(node.tests[-1][1], node)
 246
 247     def visitTryExcept(self, node):
 248         self.doSuite(node, node.body)
 249         for i in range(len(node.handlers)):
 250             a, b, h = node.handlers[i]
 251             if not a:
 252                 # It's a plain "except:".  Find the previous suite.
 253                 if i > 0:
 254                     prev = node.handlers[i-1][2]
 255                 else:
 256                     prev = node.body
 257                 self.doPlainWordSuite(prev, h)
 258             else:
 259                 self.doSuite(a, h)
 260         self.doElse(node.handlers[-1][2], node)
 261
 262     def visitTryFinally(self, node):
 263         self.doSuite(node, node.body)
 264         self.doPlainWordSuite(node.body, node.final)
 265
 266     def visitWith(self, node):
 267         self.doSuite(node, node.body)
 268
 269     def visitGlobal(self, node):
 270         # "global" statements don't execute like others (they don't call the
 271         # trace function), so don't record their line numbers.
 272         pass
 273
 274 the_coverage = None
 275
 276 class CoverageException(Exception): pass
 277
 278 class coverage:
 279     # Name of the cache file (unless environment variable is set).
 280     cache_default = ".coverage"
 281
 282     # Environment variable naming the cache file.
 283     cache_env = "COVERAGE_FILE"
 284
 285     # A dictionary with an entry for (Python source file name, line number
 286     # in that file) if that line has been executed.
 287     c = {}
 288
 289     # A map from canonical Python source file name to a dictionary in
 290     # which there's an entry for each line number that has been
 291     # executed.
 292     cexecuted = {}
 293
 294     # Cache of results of calling the analysis2() method, so that you can
 295     # specify both -r and -a without doing double work.
 296     analysis_cache = {}
 297
 298     # Cache of results of calling the canonical_filename() method, to
 299     # avoid duplicating work.
 300     canonical_filename_cache = {}
 301
 302     def __init__(self):
 303         global the_coverage
 304         if the_coverage:
 305             raise CoverageException("Only one coverage object allowed.")
 306         self.usecache = 1
 307         self.cache = None
 308         self.parallel_mode = False
 309         self.exclude_re = ''
 310         self.nesting = 0
 311         self.cstack = []
 312         self.xstack = []
 313         self.relative_dir = os.path.normcase(os.path.abspath(os.curdir)+os.sep)
 314         self.exclude('# *pragma[: ]*[nN][oO] *[cC][oO][vV][eE][rR]')
 315
 316     # t(f, x, y).  This method is passed to sys.settrace as a trace function.
 317     # See [van Rossum 2001-07-20b, 9.2] for an explanation of sys.settrace and
 318     # the arguments and return value of the trace function.
 319     # See [van Rossum 2001-07-20a, 3.2] for a description of frame and code
 320     # objects.
 321
 322     def t(self, f, w, unused):                                 #pragma: no cover
 323         if w == 'line':
 324             #print "Executing %s @ %d" % (f.f_code.co_filename, f.f_lineno)
 325             self.c[(f.f_code.co_filename, f.f_lineno)] = 1
 326             for c in self.cstack:
 327                 c[(f.f_code.co_filename, f.f_lineno)] = 1
 328         return self.t
 329
 330     def help(self, error=None):     #pragma: no cover
 331         if error:
 332             print error
 333             print
 334         print __doc__
 335         sys.exit(1)
 336
 337     def command_line(self, argv, help_fn=None):
 338         import getopt
 339         help_fn = help_fn or self.help
 340         settings = {}
 341         optmap = {
 342             '-a': 'annotate',
 343             '-c': 'collect',
 344             '-d:': 'directory=',
 345             '-e': 'erase',
 346             '-h': 'help',
 347             '-i': 'ignore-errors',
 348             '-m': 'show-missing',
 349             '-p': 'parallel-mode',
 350             '-r': 'report',
 351             '-x': 'execute',
 352             '-o:': 'omit=',
 353             }
 354         short_opts = string.join(map(lambda o: o[1:], optmap.keys()), '')
 355         long_opts = optmap.values()
 356         options, args = getopt.getopt(argv, short_opts, long_opts)
 357
 358         for o, a in options:
 359             if optmap.has_key(o):
 360                 settings[optmap[o]] = 1
 361             elif optmap.has_key(o + ':'):
 362                 settings[optmap[o + ':']] = a
 363             elif o[2:] in long_opts:
 364                 settings[o[2:]] = 1
 365             elif o[2:] + '=' in long_opts:
 366                 settings[o[2:]+'='] = a
 367             else:       #pragma: no cover
 368                 pass    # Can't get here, because getopt won't return anything unknown.
 369
 370         if settings.get('help'):
 371             help_fn()
 372
 373         for i in ['erase', 'execute']:
 374             for j in ['annotate', 'report', 'collect']:
 375                 if settings.get(i) and settings.get(j):
 376                     help_fn("You can't specify the '%s' and '%s' "
 377                               "options at the same time." % (i, j))
 378
 379         args_needed = (settings.get('execute')
 380                        or settings.get('annotate')
 381                        or settings.get('report'))
 382         action = (settings.get('erase')
 383                   or settings.get('collect')
 384                   or args_needed)
 385         if not action:
 386             help_fn("You must specify at least one of -e, -x, -c, -r, or -a.")
 387         if not args_needed and args:
 388             help_fn("Unexpected arguments: %s" % " ".join(args))
 389
 390         self.parallel_mode = settings.get('parallel-mode')
 391         self.get_ready()
 392
 393         if settings.get('erase'):
 394             self.erase()
 395         if settings.get('execute'):
 396             if not args:
 397                 help_fn("Nothing to do.")
 398             sys.argv = args
 399             self.start()
 400             import __main__
 401             sys.path[0] = os.path.dirname(sys.argv[0])
 402             # the line below is needed since otherwise __file__ gets fucked
 403             __main__.__dict__["__file__"] = sys.argv[0]
 404             execfile(sys.argv[0], __main__.__dict__)
 405         if settings.get('collect'):
 406             self.collect()
 407         if not args:
 408             args = self.cexecuted.keys()
 409
 410         ignore_errors = settings.get('ignore-errors')
 411         show_missing = settings.get('show-missing')
 412         directory = settings.get('directory=')
 413
 414         omit = settings.get('omit=')
 415         if omit is not None:
 416             omit = omit.split(',')
 417         else:
 418             omit = []
 419
 420         if settings.get('report'):
 421             self.report(args, show_missing, ignore_errors, omit_prefixes=omit)
 422         if settings.get('annotate'):
 423             self.annotate(args, directory, ignore_errors, omit_prefixes=omit)
 424
 425     def use_cache(self, usecache, cache_file=None):
 426         self.usecache = usecache
 427         if cache_file and not self.cache:
 428             self.cache_default = cache_file
 429
 430     def get_ready(self, parallel_mode=False):
 431         if self.usecache and not self.cache:
 432             self.cache = os.environ.get(self.cache_env, self.cache_default)
 433             if self.parallel_mode:
 434                 self.cache += "." + gethostname() + "." + str(os.getpid())
 435             self.restore()
 436         self.analysis_cache = {}
 437
 438     def start(self, parallel_mode=False):
 439         self.get_ready()
 440         if self.nesting == 0:                               #pragma: no cover
 441             sys.settrace(self.t)
 442             if hasattr(threading, 'settrace'):
 443                 threading.settrace(self.t)
 444         self.nesting += 1
 445
 446     def stop(self):
 447         self.nesting -= 1
 448         if self.nesting == 0:                               #pragma: no cover
 449             sys.settrace(None)
 450             if hasattr(threading, 'settrace'):
 451                 threading.settrace(None)
 452
 453     def erase(self):
 454         self.get_ready()
 455         self.c = {}
 456         self.analysis_cache = {}
 457         self.cexecuted = {}
 458         if self.cache and os.path.exists(self.cache):
 459             os.remove(self.cache)
 460
 461     def exclude(self, re):
 462         if self.exclude_re:
 463             self.exclude_re += "|"
 464         self.exclude_re += "(" + re + ")"
 465
 466     def begin_recursive(self):
 467         self.cstack.append(self.c)
 468         self.xstack.append(self.exclude_re)
 469
 470     def end_recursive(self):
 471         self.c = self.cstack.pop()
 472         self.exclude_re = self.xstack.pop()
 473
 474     # save().  Save coverage data to the coverage cache.
 475
 476     def save(self):
 477         if self.usecache and self.cache:
 478             self.canonicalize_filenames()
 479             cache = open(self.cache, 'wb')
 480             import marshal
 481             marshal.dump(self.cexecuted, cache)
 482             cache.close()
 483
 484     # restore().  Restore coverage data from the coverage cache (if it exists).
 485
 486     def restore(self):
 487         self.c = {}
 488         self.cexecuted = {}
 489         assert self.usecache
 490         if os.path.exists(self.cache):
 491             self.cexecuted = self.restore_file(self.cache)
 492
 493     def restore_file(self, file_name):
 494         try:
 495             cache = open(file_name, 'rb')
 496             import marshal
 497             cexecuted = marshal.load(cache)
 498             cache.close()
 499             if isinstance(cexecuted, types.DictType):
 500                 return cexecuted
 501             else:
 502                 return {}
 503         except:
 504             return {}
 505
 506     # collect(). Collect data in multiple files produced by parallel mode
 507
 508     def collect(self):
 509         cache_dir, local = os.path.split(self.cache)
 510         for f in os.listdir(cache_dir or '.'):
 511             if not f.startswith(local):
 512                 continue
 513
 514             full_path = os.path.join(cache_dir, f)
 515             cexecuted = self.restore_file(full_path)
 516             self.merge_data(cexecuted)
 517
 518     def merge_data(self, new_data):
 519         for file_name, file_data in new_data.items():
 520             if self.cexecuted.has_key(file_name):
 521                 self.merge_file_data(self.cexecuted[file_name], file_data)
 522             else:
 523                 self.cexecuted[file_name] = file_data
 524
 525     def merge_file_data(self, cache_data, new_data):
 526         for line_number in new_data.keys():
 527             if not cache_data.has_key(line_number):
 528                 cache_data[line_number] = new_data[line_number]
 529
 530     # canonical_filename(filename).  Return a canonical filename for the
 531     # file (that is, an absolute path with no redundant components and
 532     # normalized case).  See [GDR 2001-12-04b, 3.3].
 533
 534     def canonical_filename(self, filename):
 535         if not self.canonical_filename_cache.has_key(filename):
 536             f = filename
 537             if os.path.isabs(f) and not os.path.exists(f):
 538                 f = os.path.basename(f)
 539             if not os.path.isabs(f):
 540                 for path in [os.curdir] + sys.path:
 541                     g = os.path.join(path, f)
 542                     if os.path.exists(g):
 543                         f = g
 544                         break
 545             cf = os.path.normcase(os.path.abspath(f))
 546             self.canonical_filename_cache[filename] = cf
 547         return self.canonical_filename_cache[filename]
 548
 549     # canonicalize_filenames().  Copy results from "c" to "cexecuted",
 550     # canonicalizing filenames on the way.  Clear the "c" map.
 551
 552     def canonicalize_filenames(self):
 553         for filename, lineno in self.c.keys():
 554             if filename == '<string>':
 555                 # Can't do anything useful with exec'd strings, so skip them.
 556                 continue
 557             f = self.canonical_filename(filename)
 558             if not self.cexecuted.has_key(f):
 559                 self.cexecuted[f] = {}
 560             self.cexecuted[f][lineno] = 1
 561         self.c = {}
 562
 563     # morf_filename(morf).  Return the filename for a module or file.
 564
 565     def morf_filename(self, morf):
 566         if isinstance(morf, types.ModuleType):
 567             if not hasattr(morf, '__file__'):
 568                 raise CoverageException("Module has no __file__ attribute.")
 569             f = morf.__file__
 570         else:
 571             f = morf
 572         return self.canonical_filename(f)
 573
 574     # analyze_morf(morf).  Analyze the module or filename passed as
 575     # the argument.  If the source code can't be found, raise an error.
 576     # Otherwise, return a tuple of (1) the canonical filename of the
 577     # source code for the module, (2) a list of lines of statements
 578     # in the source code, (3) a list of lines of excluded statements,
 579     # and (4), a map of line numbers to multi-line line number ranges, for
 580     # statements that cross lines.
 581
 582     def analyze_morf(self, morf):
 583         if self.analysis_cache.has_key(morf):
 584             return self.analysis_cache[morf]
 585         filename = self.morf_filename(morf)
 586         ext = os.path.splitext(filename)[1]
 587         if ext == '.pyc':
 588             if not os.path.exists(filename[:-1]):
 589                 raise CoverageException(
 590                     "No source for compiled code '%s'." % filename
 591                     )
 592             filename = filename[:-1]
 593         source = open(filename, 'r')
 594         try:
 595             lines, excluded_lines, line_map = self.find_executable_statements(
 596                 source.read(), exclude=self.exclude_re
 597                 )
 598         except SyntaxError, synerr:
 599             raise CoverageException(
 600                 "Couldn't parse '%s' as Python source: '%s' at line %d" %
 601                     (filename, synerr.msg, synerr.lineno)
 602                 )
 603         source.close()
 604         result = filename, lines, excluded_lines, line_map
 605         self.analysis_cache[morf] = result
 606         return result
 607
 608     def first_line_of_tree(self, tree):
 609         while True:
 610             if len(tree) == 3 and type(tree[2]) == type(1):
 611                 return tree[2]
 612             tree = tree[1]
 613
 614     def last_line_of_tree(self, tree):
 615         while True:
 616             if len(tree) == 3 and type(tree[2]) == type(1):
 617                 return tree[2]
 618             tree = tree[-1]
 619
 620     def find_docstring_pass_pair(self, tree, spots):
 621         for i in range(1, len(tree)):
 622             if self.is_string_constant(tree[i]) and self.is_pass_stmt(tree[i+1]):
 623                 first_line = self.first_line_of_tree(tree[i])
 624                 last_line = self.last_line_of_tree(tree[i+1])
 625                 self.record_multiline(spots, first_line, last_line)
 626
 627     def is_string_constant(self, tree):
 628         try:
 629             return tree[0] == symbol.stmt and tree[1][1][1][0] == symbol.expr_stmt
 630         except:
 631             return False
 632
 633     def is_pass_stmt(self, tree):
 634         try:
 635             return tree[0] == symbol.stmt and tree[1][1][1][0] == symbol.pass_stmt
 636         except:
 637             return False
 638
 639     def record_multiline(self, spots, i, j):
 640         for l in range(i, j+1):
 641             spots[l] = (i, j)
 642
 643     def get_suite_spots(self, tree, spots):
 644         """ Analyze a parse tree to find suite introducers which span a number
 645             of lines.
 646         """
 647         for i in range(1, len(tree)):
 648             if type(tree[i]) == type(()):
 649                 if tree[i][0] == symbol.suite:
 650                     # Found a suite, look back for the colon and keyword.
 651                     lineno_colon = lineno_word = None
 652                     for j in range(i-1, 0, -1):
 653                         if tree[j][0] == token.COLON:
 654                             # Colons are never executed themselves: we want the
 655                             # line number of the last token before the colon.
 656                             lineno_colon = self.last_line_of_tree(tree[j-1])
 657                         elif tree[j][0] == token.NAME:
 658                             if tree[j][1] == 'elif':
 659                                 # Find the line number of the first non-terminal
 660                                 # after the keyword.
 661                                 t = tree[j+1]
 662                                 while t and token.ISNONTERMINAL(t[0]):
 663                                     t = t[1]
 664                                 if t:
 665                                     lineno_word = t[2]
 666                             else:
 667                                 lineno_word = tree[j][2]
 668                             break
 669                         elif tree[j][0] == symbol.except_clause:
 670                             # "except" clauses look like:
 671                             # ('except_clause', ('NAME', 'except', lineno), ...)
 672                             if tree[j][1][0] == token.NAME:
 673                                 lineno_word = tree[j][1][2]
 674                                 break
 675                     if lineno_colon and lineno_word:
 676                         # Found colon and keyword, mark all the lines
 677                         # between the two with the two line numbers.
 678                         self.record_multiline(spots, lineno_word, lineno_colon)
 679
 680                     # "pass" statements are tricky: different versions of Python
 681                     # treat them differently, especially in the common case of a
 682                     # function with a doc string and a single pass statement.
 683                     self.find_docstring_pass_pair(tree[i], spots)
 684
 685                 elif tree[i][0] == symbol.simple_stmt:
 686                     first_line = self.first_line_of_tree(tree[i])
 687                     last_line = self.last_line_of_tree(tree[i])
 688                     if first_line != last_line:
 689                         self.record_multiline(spots, first_line, last_line)
 690                 self.get_suite_spots(tree[i], spots)
 691
 692     def find_executable_statements(self, text, exclude=None):
 693         # Find lines which match an exclusion pattern.
 694         excluded = {}
 695         suite_spots = {}
 696         if exclude:
 697             reExclude = re.compile(exclude)
 698             lines = text.split('\n')
 699             for i in range(len(lines)):
 700                 if reExclude.search(lines[i]):
 701                     excluded[i+1] = 1
 702
 703         # Parse the code and analyze the parse tree to find out which statements
 704         # are multiline, and where suites begin and end.
 705         import parser
 706         tree = parser.suite(text+'\n\n').totuple(1)
 707         self.get_suite_spots(tree, suite_spots)
 708         #print "Suite spots:", suite_spots
 709
 710         # Use the compiler module to parse the text and find the executable
 711         # statements.  We add newlines to be impervious to final partial lines.
 712         statements = {}
 713         ast = compiler.parse(text+'\n\n')
 714         visitor = StatementFindingAstVisitor(statements, excluded, suite_spots)
 715         compiler.walk(ast, visitor, walker=visitor)
 716
 717         lines = statements.keys()
 718         lines.sort()
 719         excluded_lines = excluded.keys()
 720         excluded_lines.sort()
 721         return lines, excluded_lines, suite_spots
 722
 723     # format_lines(statements, lines).  Format a list of line numbers
 724     # for printing by coalescing groups of lines as long as the lines
 725     # represent consecutive statements.  This will coalesce even if
 726     # there are gaps between statements, so if statements =
 727     # [1,2,3,4,5,10,11,12,13,14] and lines = [1,2,5,10,11,13,14] then
 728     # format_lines will return "1-2, 5-11, 13-14".
 729
 730     def format_lines(self, statements, lines):
 731         pairs = []
 732         i = 0
 733         j = 0
 734         start = None
 735         pairs = []
 736         while i < len(statements) and j < len(lines):
 737             if statements[i] == lines[j]:
 738                 if start is None:
 739                     start = lines[j]
 740                 end = lines[j]
 741                 j = j + 1
 742             elif start:
 743                 pairs.append((start, end))
 744                 start = None
 745             i = i + 1
 746         if start:
 747             pairs.append((start, end))
 748         def stringify(pair):
 749             start, end = pair
 750             if start == end:
 751                 return "%d" % start
 752             else:
 753                 return "%d-%d" % (start, end)
 754         ret = string.join(map(stringify, pairs), ", ")
 755         return ret
 756
 757     # Backward compatibility with version 1.
 758     def analysis(self, morf):
 759         f, s, _, m, mf = self.analysis2(morf)
 760         return f, s, m, mf
 761
 762     def analysis2(self, morf):
 763         filename, statements, excluded, line_map = self.analyze_morf(morf)
 764         self.canonicalize_filenames()
 765         if not self.cexecuted.has_key(filename):
 766             self.cexecuted[filename] = {}
 767         missing = []
 768         for line in statements:
 769             lines = line_map.get(line, [line, line])
 770             for l in range(lines[0], lines[1]+1):
 771                 if self.cexecuted[filename].has_key(l):
 772                     break
 773             else:
 774                 missing.append(line)
 775         return (filename, statements, excluded, missing,
 776                 self.format_lines(statements, missing))
 777
 778     def relative_filename(self, filename):
 779         """ Convert filename to relative filename from self.relative_dir.
 780         """
 781         return filename.replace(self.relative_dir, "")
 782
 783     def morf_name(self, morf):
 784         """ Return the name of morf as used in report.
 785         """
 786         if isinstance(morf, types.ModuleType):
 787             return morf.__name__
 788         else:
 789             return self.relative_filename(os.path.splitext(morf)[0])
 790
 791     def filter_by_prefix(self, morfs, omit_prefixes):
 792         """ Return list of morfs where the morf name does not begin
 793             with any one of the omit_prefixes.
 794         """
 795         filtered_morfs = []
 796         for morf in morfs:
 797             for prefix in omit_prefixes:
 798                 if self.morf_name(morf).startswith(prefix):
 799                     break
 800             else:
 801                 filtered_morfs.append(morf)
 802
 803         return filtered_morfs
 804
 805     def morf_name_compare(self, x, y):
 806         return cmp(self.morf_name(x), self.morf_name(y))
 807
 808     def report(self, morfs, show_missing=1, ignore_errors=0, file=None, omit_prefixes=[]):
 809         if not isinstance(morfs, types.ListType):
 810             morfs = [morfs]
 811         # On windows, the shell doesn't expand wildcards.  Do it here.
 812         globbed = []
 813         for morf in morfs:
 814             if isinstance(morf, strclass):
 815                 globbed.extend(glob.glob(morf))
 816             else:
 817                 globbed.append(morf)
 818         morfs = globbed
 819
 820         morfs = self.filter_by_prefix(morfs, omit_prefixes)
 821         morfs.sort(self.morf_name_compare)
 822
 823         max_name = max([5,] + map(len, map(self.morf_name, morfs)))
 824         fmt_name = "%%- %ds  " % max_name
 825         fmt_err = fmt_name + "%s: %s"
 826         header = fmt_name % "Name" + " Stmts   Exec  Cover"
 827         fmt_coverage = fmt_name + "% 6d % 6d % 5d%%"
 828         if show_missing:
 829             header = header + "   Missing"
 830             fmt_coverage = fmt_coverage + "   %s"
 831         if not file:
 832             file = sys.stdout
 833         print >>file, header
 834         print >>file, "-" * len(header)
 835         total_statements = 0
 836         total_executed = 0
 837         for morf in morfs:
 838             name = self.morf_name(morf)
 839             try:
 840                 _, statements, _, missing, readable  = self.analysis2(morf)
 841                 n = len(statements)
 842                 m = n - len(missing)
 843                 if n > 0:
 844                     pc = 100.0 * m / n
 845                 else:
 846                     pc = 100.0
 847                 args = (name, n, m, pc)
 848                 if show_missing:
 849                     args = args + (readable,)
 850                 print >>file, fmt_coverage % args
 851                 total_statements = total_statements + n
 852                 total_executed = total_executed + m
 853             except KeyboardInterrupt:                       #pragma: no cover
 854                 raise
 855             except:
 856                 if not ignore_errors:
 857                     typ, msg = sys.exc_info()[:2]
 858                     print >>file, fmt_err % (name, typ, msg)
 859         if len(morfs) > 1:
 860             print >>file, "-" * len(header)
 861             if total_statements > 0:
 862                 pc = 100.0 * total_executed / total_statements
 863             else:
 864                 pc = 100.0
 865             args = ("TOTAL", total_statements, total_executed, pc)
 866             if show_missing:
 867                 args = args + ("",)
 868             print >>file, fmt_coverage % args
 869
 870     # annotate(morfs, ignore_errors).
 871
 872     blank_re = re.compile(r"\s*(#|$)")
 873     else_re = re.compile(r"\s*else\s*:\s*(#|$)")
 874
 875     def annotate(self, morfs, directory=None, ignore_errors=0, omit_prefixes=[]):
 876         morfs = self.filter_by_prefix(morfs, omit_prefixes)
 877         for morf in morfs:
 878             try:
 879                 filename, statements, excluded, missing, _ = self.analysis2(morf)
 880                 self.annotate_file(filename, statements, excluded, missing, directory)
 881             except KeyboardInterrupt:
 882                 raise
 883             except:
 884                 if not ignore_errors:
 885                     raise
 886
 887     def annotate_file(self, filename, statements, excluded, missing, directory=None):
 888         source = open(filename, 'r')
 889         if directory:
 890             dest_file = os.path.join(directory,
 891                                      os.path.basename(filename)
 892                                      + ',cover')
 893         else:
 894             dest_file = filename + ',cover'
 895         dest = open(dest_file, 'w')
 896         lineno = 0
 897         i = 0
 898         j = 0
 899         covered = 1
 900         while 1:
 901             line = source.readline()
 902             if line == '':
 903                 break
 904             lineno = lineno + 1
 905             while i < len(statements) and statements[i] < lineno:
 906                 i = i + 1
 907             while j < len(missing) and missing[j] < lineno:
 908                 j = j + 1
 909             if i < len(statements) and statements[i] == lineno:
 910                 covered = j >= len(missing) or missing[j] > lineno
 911             if self.blank_re.match(line):
 912                 dest.write('  ')
 913             elif self.else_re.match(line):
 914                 # Special logic for lines containing only 'else:'.
 915                 # See [GDR 2001-12-04b, 3.2].
 916                 if i >= len(statements) and j >= len(missing):
 917                     dest.write('! ')
 918                 elif i >= len(statements) or j >= len(missing):
 919                     dest.write('> ')
 920                 elif statements[i] == missing[j]:
 921                     dest.write('! ')
 922                 else:
 923                     dest.write('> ')
 924             elif lineno in excluded:
 925                 dest.write('- ')
 926             elif covered:
 927                 dest.write('> ')
 928             else:
 929                 dest.write('! ')
 930             dest.write(line)
 931         source.close()
 932         dest.close()
 933
 934 # Singleton object.
 935 the_coverage = coverage()
 936
 937 # Module functions call methods in the singleton object.
 938 def use_cache(*args, **kw):
 939     return the_coverage.use_cache(*args, **kw)
 940
 941 def start(*args, **kw):
 942     return the_coverage.start(*args, **kw)
 943
 944 def stop(*args, **kw):
 945     return the_coverage.stop(*args, **kw)
 946
 947 def erase(*args, **kw):
 948     return the_coverage.erase(*args, **kw)
 949
 950 def begin_recursive(*args, **kw):
 951     return the_coverage.begin_recursive(*args, **kw)
 952
 953 def end_recursive(*args, **kw):
 954     return the_coverage.end_recursive(*args, **kw)
 955
 956 def exclude(*args, **kw):
 957     return the_coverage.exclude(*args, **kw)
 958
 959 def analysis(*args, **kw):
 960     return the_coverage.analysis(*args, **kw)
 961
 962 def analysis2(*args, **kw):
 963     return the_coverage.analysis2(*args, **kw)
 964
 965 def report(*args, **kw):
 966     return the_coverage.report(*args, **kw)
 967
 968 def annotate(*args, **kw):
 969     return the_coverage.annotate(*args, **kw)
 970
 971 def annotate_file(*args, **kw):
 972     return the_coverage.annotate_file(*args, **kw)
 973
 974 # Save coverage data when Python exits.  (The atexit module wasn't
 975 # introduced until Python 2.0, so use sys.exitfunc when it's not
 976 # available.)
 977 try:
 978     import atexit
 979     atexit.register(the_coverage.save)
 980 except ImportError:
 981     sys.exitfunc = the_coverage.save
 982
 983 # Command-line interface.
 984 if __name__ == '__main__':
 985     the_coverage.command_line(sys.argv[1:])
 986
 987
 988 # A. REFERENCES
 989 #
 990 # [GDR 2001-12-04a] "Statement coverage for Python"; Gareth Rees;
 991 # Ravenbrook Limited; 2001-12-04;
 992 # <http://www.nedbatchelder.com/code/modules/rees-coverage.html>.
 993 #
 994 # [GDR 2001-12-04b] "Statement coverage for Python: design and
 995 # analysis"; Gareth Rees; Ravenbrook Limited; 2001-12-04;
 996 # <http://www.nedbatchelder.com/code/modules/rees-design.html>.
 997 #
 998 # [van Rossum 2001-07-20a] "Python Reference Manual (releae 2.1.1)";
 999 # Guide van Rossum; 2001-07-20;
1000 # <http://www.python.org/doc/2.1.1/ref/ref.html>.
1001 #
1002 # [van Rossum 2001-07-20b] "Python Library Reference"; Guido van Rossum;
1003 # 2001-07-20; <http://www.python.org/doc/2.1.1/lib/lib.html>.
1004 #
1005 #
1006 # B. DOCUMENT HISTORY
1007 #
1008 # 2001-12-04 GDR Created.
1009 #
1010 # 2001-12-06 GDR Added command-line interface and source code
1011 # annotation.
1012 #
1013 # 2001-12-09 GDR Moved design and interface to separate documents.
1014 #
1015 # 2001-12-10 GDR Open cache file as binary on Windows.  Allow
1016 # simultaneous -e and -x, or -a and -r.
1017 #
1018 # 2001-12-12 GDR Added command-line help.  Cache analysis so that it
1019 # only needs to be done once when you specify -a and -r.
1020 #
1021 # 2001-12-13 GDR Improved speed while recording.  Portable between
1022 # Python 1.5.2 and 2.1.1.
1023 #
1024 # 2002-01-03 GDR Module-level functions work correctly.
1025 #
1026 # 2002-01-07 GDR Update sys.path when running a file with the -x option,
1027 # so that it matches the value the program would get if it were run on
1028 # its own.
1029 #
1030 # 2004-12-12 NMB Significant code changes.
1031 # - Finding executable statements has been rewritten so that docstrings and
1032 #   other quirks of Python execution aren't mistakenly identified as missing
1033 #   lines.
1034 # - Lines can be excluded from consideration, even entire suites of lines.
1035 # - The filesystem cache of covered lines can be disabled programmatically.
1036 # - Modernized the code.
1037 #
1038 # 2004-12-14 NMB Minor tweaks.  Return 'analysis' to its original behavior
1039 # and add 'analysis2'.  Add a global for 'annotate', and factor it, adding
1040 # 'annotate_file'.
1041 #
1042 # 2004-12-31 NMB Allow for keyword arguments in the module global functions.
1043 # Thanks, Allen.
1044 #
1045 # 2005-12-02 NMB Call threading.settrace so that all threads are measured.
1046 # Thanks Martin Fuzzey. Add a file argument to report so that reports can be
1047 # captured to a different destination.
1048 #
1049 # 2005-12-03 NMB coverage.py can now measure itself.
1050 #
1051 # 2005-12-04 NMB Adapted Greg Rogers' patch for using relative filenames,
1052 # and sorting and omitting files to report on.
1053 #
1054 # 2006-07-23 NMB Applied Joseph Tate's patch for function decorators.
1055 #
1056 # 2006-08-21 NMB Applied Sigve Tjora and Mark van der Wal's fixes for argument
1057 # handling.
1058 #
1059 # 2006-08-22 NMB Applied Geoff Bache's parallel mode patch.
1060 #
1061 # 2006-08-23 NMB Refactorings to improve testability.  Fixes to command-line
1062 # logic for parallel mode and collect.
1063 #
1064 # 2006-08-25 NMB "#pragma: nocover" is excluded by default.
1065 #
1066 # 2006-09-10 NMB Properly ignore docstrings and other constant expressions that
1067 # appear in the middle of a function, a problem reported by Tim Leslie.
1068 # Minor changes to avoid lint warnings.
1069 #
1070 # 2006-09-17 NMB coverage.erase() shouldn't clobber the exclude regex.
1071 # Change how parallel mode is invoked, and fix erase() so that it erases the
1072 # cache when called programmatically.
1073 #
1074 # 2007-07-21 NMB In reports, ignore code executed from strings, since we can't
1075 # do anything useful with it anyway.
1076 # Better file handling on Linux, thanks Guillaume Chazarain.
1077 # Better shell support on Windows, thanks Noel O'Boyle.
1078 # Python 2.2 support maintained, thanks Catherine Proulx.
1079 #
1080 # 2007-07-22 NMB Python 2.5 now fully supported. The method of dealing with
1081 # multi-line statements is now less sensitive to the exact line that Python
1082 # reports during execution. Pass statements are handled specially so that their
1083 # disappearance during execution won't throw off the measurement.
1084 #
1085 # 2007-07-23 NMB Now Python 2.5 is *really* fully supported: the body of the
1086 # new with statement is counted as executable.
1087 #
1088 # 2007-07-29 NMB Better packaging.
1089 #
1090 # 2007-09-30 NMB Don't try to predict whether a file is Python source based on
1091 # the extension. Extensionless files are often Pythons scripts. Instead, simply
1092 # parse the file and catch the syntax errors.  Hat tip to Ben Finney.
1093
1094 # C. COPYRIGHT AND LICENCE
1095 #
1096 # Copyright 2001 Gareth Rees.  All rights reserved.
1097 # Copyright 2004-2007 Ned Batchelder.  All rights reserved.
1098 #
1099 # Redistribution and use in source and binary forms, with or without
1100 # modification, are permitted provided that the following conditions are
1101 # met:
1102 #
1103 # 1. Redistributions of source code must retain the above copyright
1104 #    notice, this list of conditions and the following disclaimer.
1105 #
1106 # 2. Redistributions in binary form must reproduce the above copyright
1107 #    notice, this list of conditions and the following disclaimer in the
1108 #    documentation and/or other materials provided with the
1109 #    distribution.
1110 #
1111 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1112 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1113 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1114 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
1115 # HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
1116 # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
1117 # BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
1118 # OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1119 # ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
1120 # TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
1121 # USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
1122 # DAMAGE.
1123 #
1124 # $Id: coverage.py 79 2007-10-01 01:01:52Z nedbat $