codekingpro/portable-devtools
114k
1# portions copyright 2001, Autonomous Zones Industries, Inc., all rights...2# err... reserved and offered to the public under the terms of the3# Python 2.2 license.4# Author: Zooko O'Whielacronx5# http://zooko.com/6# mailto:zooko@zooko.com7#8# Copyright 2000, Mojam Media, Inc., all rights reserved.9# Author: Skip Montanaro10#11# Copyright 1999, Bioreason, Inc., all rights reserved.12# Author: Andrew Dalke13#14# Copyright 1995-1997, Automatrix, Inc., all rights reserved.15# Author: Skip Montanaro16#17# Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.18#19#20# Permission to use, copy, modify, and distribute this Python software and21# its associated documentation for any purpose without fee is hereby22# granted, provided that the above copyright notice appears in all copies,23# and that both that copyright notice and this permission notice appear in24# supporting documentation, and that the name of neither Automatrix,25# Bioreason or Mojam Media be used in advertising or publicity pertaining to26# distribution of the software without specific, written prior permission.27#28"""program/module to trace Python program or function execution29 30Sample use, command line:31 trace.py -c -f counts --ignore-dir '$prefix' spam.py eggs32 trace.py -t --ignore-dir '$prefix' spam.py eggs33 trace.py --trackcalls spam.py eggs34 35Sample use, programmatically36 import sys37 38 # create a Trace object, telling it what to ignore, and whether to39 # do tracing or line-counting or both.40 tracer = trace.Trace(ignoredirs=[sys.base_prefix, sys.base_exec_prefix,],41 trace=0, count=1)42 # run the new command using the given tracer43 tracer.run('main()')44 # make a report, placing output in /tmp45 r = tracer.results()46 r.write_results(show_missing=True, coverdir="/tmp")47"""48__all__ = ['Trace', 'CoverageResults']49 50import io51import linecache52import os53import sys54import sysconfig55import token56import tokenize57import inspect58import gc59import dis60import pickle61from time import monotonic as _time62 63import threading64 65PRAGMA_NOCOVER = "#pragma NO COVER"66 67class _Ignore:68 def __init__(self, modules=None, dirs=None):69 self._mods = set() if not modules else set(modules)70 self._dirs = [] if not dirs else [os.path.normpath(d)71 for d in dirs]72 self._ignore = { '<string>': 1 }73 74 def names(self, filename, modulename):75 if modulename in self._ignore:76 return self._ignore[modulename]77 78 # haven't seen this one before, so see if the module name is79 # on the ignore list.80 if modulename in self._mods: # Identical names, so ignore81 self._ignore[modulename] = 182 return 183 84 # check if the module is a proper submodule of something on85 # the ignore list86 for mod in self._mods:87 # Need to take some care since ignoring88 # "cmp" mustn't mean ignoring "cmpcache" but ignoring89 # "Spam" must also mean ignoring "Spam.Eggs".90 if modulename.startswith(mod + '.'):91 self._ignore[modulename] = 192 return 193 94 # Now check that filename isn't in one of the directories95 if filename is None:96 # must be a built-in, so we must ignore97 self._ignore[modulename] = 198 return 199 100 # Ignore a file when it contains one of the ignorable paths101 for d in self._dirs:102 # The '+ os.sep' is to ensure that d is a parent directory,103 # as compared to cases like:104 # d = "/usr/local"105 # filename = "/usr/local.py"106 # or107 # d = "/usr/local.py"108 # filename = "/usr/local.py"109 if filename.startswith(d + os.sep):110 self._ignore[modulename] = 1111 return 1112 113 # Tried the different ways, so we don't ignore this module114 self._ignore[modulename] = 0115 return 0116 117def _modname(path):118 """Return a plausible module name for the path."""119 120 base = os.path.basename(path)121 filename, ext = os.path.splitext(base)122 return filename123 124def _fullmodname(path):125 """Return a plausible module name for the path."""126 127 # If the file 'path' is part of a package, then the filename isn't128 # enough to uniquely identify it. Try to do the right thing by129 # looking in sys.path for the longest matching prefix. We'll130 # assume that the rest is the package name.131 132 comparepath = os.path.normcase(path)133 longest = ""134 for dir in sys.path:135 dir = os.path.normcase(dir)136 if comparepath.startswith(dir) and comparepath[len(dir)] == os.sep:137 if len(dir) > len(longest):138 longest = dir139 140 if longest:141 base = path[len(longest) + 1:]142 else:143 base = path144 # the drive letter is never part of the module name145 drive, base = os.path.splitdrive(base)146 base = base.replace(os.sep, ".")147 if os.altsep:148 base = base.replace(os.altsep, ".")149 filename, ext = os.path.splitext(base)150 return filename.lstrip(".")151 152class CoverageResults:153 def __init__(self, counts=None, calledfuncs=None, infile=None,154 callers=None, outfile=None):155 self.counts = counts156 if self.counts is None:157 self.counts = {}158 self.counter = self.counts.copy() # map (filename, lineno) to count159 self.calledfuncs = calledfuncs160 if self.calledfuncs is None:161 self.calledfuncs = {}162 self.calledfuncs = self.calledfuncs.copy()163 self.callers = callers164 if self.callers is None:165 self.callers = {}166 self.callers = self.callers.copy()167 self.infile = infile168 self.outfile = outfile169 if self.infile:170 # Try to merge existing counts file.171 try:172 with open(self.infile, 'rb') as f:173 counts, calledfuncs, callers = pickle.load(f)174 self.update(self.__class__(counts, calledfuncs, callers=callers))175 except (OSError, EOFError, ValueError) as err:176 print(("Skipping counts file %r: %s"177 % (self.infile, err)), file=sys.stderr)178 179 def is_ignored_filename(self, filename):180 """Return True if the filename does not refer to a file181 we want to have reported.182 """183 return filename.startswith('<') and filename.endswith('>')184 185 def update(self, other):186 """Merge in the data from another CoverageResults"""187 counts = self.counts188 calledfuncs = self.calledfuncs189 callers = self.callers190 other_counts = other.counts191 other_calledfuncs = other.calledfuncs192 other_callers = other.callers193 194 for key in other_counts:195 counts[key] = counts.get(key, 0) + other_counts[key]196 197 for key in other_calledfuncs:198 calledfuncs[key] = 1199 200 for key in other_callers:201 callers[key] = 1202 203 def write_results(self, show_missing=True, summary=False, coverdir=None, *,204 ignore_missing_files=False):205 """206 Write the coverage results.207 208 :param show_missing: Show lines that had no hits.209 :param summary: Include coverage summary per module.210 :param coverdir: If None, the results of each module are placed in its211 directory, otherwise it is included in the directory212 specified.213 :param ignore_missing_files: If True, counts for files that no longer214 exist are silently ignored. Otherwise, a missing file215 will raise a FileNotFoundError.216 """217 if self.calledfuncs:218 print()219 print("functions called:")220 calls = self.calledfuncs221 for filename, modulename, funcname in sorted(calls):222 print(("filename: %s, modulename: %s, funcname: %s"223 % (filename, modulename, funcname)))224 225 if self.callers:226 print()227 print("calling relationships:")228 lastfile = lastcfile = ""229 for ((pfile, pmod, pfunc), (cfile, cmod, cfunc)) \230 in sorted(self.callers):231 if pfile != lastfile:232 print()233 print("***", pfile, "***")234 lastfile = pfile235 lastcfile = ""236 if cfile != pfile and lastcfile != cfile:237 print(" -->", cfile)238 lastcfile = cfile239 print(" %s.%s -> %s.%s" % (pmod, pfunc, cmod, cfunc))240 241 # turn the counts data ("(filename, lineno) = count") into something242 # accessible on a per-file basis243 per_file = {}244 for filename, lineno in self.counts:245 lines_hit = per_file[filename] = per_file.get(filename, {})246 lines_hit[lineno] = self.counts[(filename, lineno)]247 248 # accumulate summary info, if needed249 sums = {}250 251 for filename, count in per_file.items():252 if self.is_ignored_filename(filename):253 continue254 255 if filename.endswith(".pyc"):256 filename = filename[:-1]257 258 if ignore_missing_files and not os.path.isfile(filename):259 continue260 261 if coverdir is None:262 dir = os.path.dirname(os.path.abspath(filename))263 modulename = _modname(filename)264 else:265 dir = coverdir266 os.makedirs(dir, exist_ok=True)267 modulename = _fullmodname(filename)268 269 # If desired, get a list of the line numbers which represent270 # executable content (returned as a dict for better lookup speed)271 if show_missing:272 lnotab = _find_executable_linenos(filename)273 else:274 lnotab = {}275 source = linecache.getlines(filename)276 coverpath = os.path.join(dir, modulename + ".cover")277 with open(filename, 'rb') as fp:278 encoding, _ = tokenize.detect_encoding(fp.readline)279 n_hits, n_lines = self.write_results_file(coverpath, source,280 lnotab, count, encoding)281 if summary and n_lines:282 sums[modulename] = n_lines, n_hits, modulename, filename283 284 if summary and sums:285 print("lines cov% module (path)")286 for m in sorted(sums):287 n_lines, n_hits, modulename, filename = sums[m]288 print(f"{n_lines:5d} {n_hits/n_lines:.1%} {modulename} ({filename})")289 290 if self.outfile:291 # try and store counts and module info into self.outfile292 try:293 with open(self.outfile, 'wb') as f:294 pickle.dump((self.counts, self.calledfuncs, self.callers),295 f, 1)296 except OSError as err:297 print("Can't save counts files because %s" % err, file=sys.stderr)298 299 def write_results_file(self, path, lines, lnotab, lines_hit, encoding=None):300 """Return a coverage results file in path."""301 # ``lnotab`` is a dict of executable lines, or a line number "table"302 303 try:304 outfile = open(path, "w", encoding=encoding)305 except OSError as err:306 print(("trace: Could not open %r for writing: %s "307 "- skipping" % (path, err)), file=sys.stderr)308 return 0, 0309 310 n_lines = 0311 n_hits = 0312 with outfile:313 for lineno, line in enumerate(lines, 1):314 # do the blank/comment match to try to mark more lines315 # (help the reader find stuff that hasn't been covered)316 if lineno in lines_hit:317 outfile.write("%5d: " % lines_hit[lineno])318 n_hits += 1319 n_lines += 1320 elif lineno in lnotab and not PRAGMA_NOCOVER in line:321 # Highlight never-executed lines, unless the line contains322 # #pragma: NO COVER323 outfile.write(">>>>>> ")324 n_lines += 1325 else:326 outfile.write(" ")327 outfile.write(line.expandtabs(8))328 329 return n_hits, n_lines330 331def _find_lines_from_code(code, strs):332 """Return dict where keys are lines in the line number table."""333 linenos = {}334 335 for _, lineno in dis.findlinestarts(code):336 if lineno not in strs:337 linenos[lineno] = 1338 339 return linenos340 341def _find_lines(code, strs):342 """Return lineno dict for all code objects reachable from code."""343 # get all of the lineno information from the code of this scope level344 linenos = _find_lines_from_code(code, strs)345 346 # and check the constants for references to other code objects347 for c in code.co_consts:348 if inspect.iscode(c):349 # find another code object, so recurse into it350 linenos.update(_find_lines(c, strs))351 return linenos352 353def _find_strings(filename, encoding=None):354 """Return a dict of possible docstring positions.355 356 The dict maps line numbers to strings. There is an entry for357 line that contains only a string or a part of a triple-quoted358 string.359 """360 d = {}361 # If the first token is a string, then it's the module docstring.362 # Add this special case so that the test in the loop passes.363 prev_ttype = token.INDENT364 with open(filename, encoding=encoding) as f:365 tok = tokenize.generate_tokens(f.readline)366 for ttype, tstr, start, end, line in tok:367 if ttype == token.STRING:368 if prev_ttype == token.INDENT:369 sline, scol = start370 eline, ecol = end371 for i in range(sline, eline + 1):372 d[i] = 1373 prev_ttype = ttype374 return d375 376def _find_executable_linenos(filename):377 """Return dict where keys are line numbers in the line number table."""378 try:379 with tokenize.open(filename) as f:380 prog = f.read()381 encoding = f.encoding382 except OSError as err:383 print(("Not printing coverage data for %r: %s"384 % (filename, err)), file=sys.stderr)385 return {}386 code = compile(prog, filename, "exec")387 strs = _find_strings(filename, encoding)388 return _find_lines(code, strs)389 390class Trace:391 def __init__(self, count=1, trace=1, countfuncs=0, countcallers=0,392 ignoremods=(), ignoredirs=(), infile=None, outfile=None,393 timing=False):394 """395 @param count true iff it should count number of times each396 line is executed397 @param trace true iff it should print out each line that is398 being counted399 @param countfuncs true iff it should just output a list of400 (filename, modulename, funcname,) for functions401 that were called at least once; This overrides402 'count' and 'trace'403 @param ignoremods a list of the names of modules to ignore404 @param ignoredirs a list of the names of directories to ignore405 all of the (recursive) contents of406 @param infile file from which to read stored counts to be407 added into the results408 @param outfile file in which to write the results409 @param timing true iff timing information be displayed410 """411 self.infile = infile412 self.outfile = outfile413 self.ignore = _Ignore(ignoremods, ignoredirs)414 self.counts = {} # keys are (filename, linenumber)415 self.pathtobasename = {} # for memoizing os.path.basename416 self.donothing = 0417 self.trace = trace418 self._calledfuncs = {}419 self._callers = {}420 self._caller_cache = {}421 self.start_time = None422 if timing:423 self.start_time = _time()424 if countcallers:425 self.globaltrace = self.globaltrace_trackcallers426 elif countfuncs:427 self.globaltrace = self.globaltrace_countfuncs428 elif trace and count:429 self.globaltrace = self.globaltrace_lt430 self.localtrace = self.localtrace_trace_and_count431 elif trace:432 self.globaltrace = self.globaltrace_lt433 self.localtrace = self.localtrace_trace434 elif count:435 self.globaltrace = self.globaltrace_lt436 self.localtrace = self.localtrace_count437 else:438 # Ahem -- do nothing? Okay.439 self.donothing = 1440 441 def run(self, cmd):442 import __main__443 dict = __main__.__dict__444 self.runctx(cmd, dict, dict)445 446 def runctx(self, cmd, globals=None, locals=None):447 if globals is None: globals = {}448 if locals is None: locals = {}449 if not self.donothing:450 threading.settrace(self.globaltrace)451 sys.settrace(self.globaltrace)452 try:453 exec(cmd, globals, locals)454 finally:455 if not self.donothing:456 sys.settrace(None)457 threading.settrace(None)458 459 def runfunc(self, func, /, *args, **kw):460 result = None461 if not self.donothing:462 sys.settrace(self.globaltrace)463 try:464 result = func(*args, **kw)465 finally:466 if not self.donothing:467 sys.settrace(None)468 return result469 470 def file_module_function_of(self, frame):471 code = frame.f_code472 filename = code.co_filename473 if filename:474 modulename = _modname(filename)475 else:476 modulename = None477 478 funcname = code.co_name479 clsname = None480 if code in self._caller_cache:481 if self._caller_cache[code] is not None:482 clsname = self._caller_cache[code]483 else:484 self._caller_cache[code] = None485 ## use of gc.get_referrers() was suggested by Michael Hudson486 # all functions which refer to this code object487 funcs = [f for f in gc.get_referrers(code)488 if inspect.isfunction(f)]489 # require len(func) == 1 to avoid ambiguity caused by calls to490 # new.function(): "In the face of ambiguity, refuse the491 # temptation to guess."492 if len(funcs) == 1:493 dicts = [d for d in gc.get_referrers(funcs[0])494 if isinstance(d, dict)]495 if len(dicts) == 1:496 classes = [c for c in gc.get_referrers(dicts[0])497 if hasattr(c, "__bases__")]498 if len(classes) == 1:499 # ditto for new.classobj()500 clsname = classes[0].__name__501 # cache the result - assumption is that new.* is502 # not called later to disturb this relationship503 # _caller_cache could be flushed if functions in504 # the new module get called.505 self._caller_cache[code] = clsname506 if clsname is not None:507 funcname = "%s.%s" % (clsname, funcname)508 509 return filename, modulename, funcname510 511 def globaltrace_trackcallers(self, frame, why, arg):512 """Handler for call events.513 514 Adds information about who called who to the self._callers dict.515 """516 if why == 'call':517 # XXX Should do a better job of identifying methods518 this_func = self.file_module_function_of(frame)519 parent_func = self.file_module_function_of(frame.f_back)520 self._callers[(parent_func, this_func)] = 1521 522 def globaltrace_countfuncs(self, frame, why, arg):523 """Handler for call events.524 525 Adds (filename, modulename, funcname) to the self._calledfuncs dict.526 """527 if why == 'call':528 this_func = self.file_module_function_of(frame)529 self._calledfuncs[this_func] = 1530 531 def globaltrace_lt(self, frame, why, arg):532 """Handler for call events.533 534 If the code block being entered is to be ignored, returns 'None',535 else returns self.localtrace.536 """537 if why == 'call':538 code = frame.f_code539 filename = frame.f_globals.get('__file__', None)540 if filename:541 # XXX _modname() doesn't work right for packages, so542 # the ignore support won't work right for packages543 modulename = _modname(filename)544 if modulename is not None:545 ignore_it = self.ignore.names(filename, modulename)546 if not ignore_it:547 if self.trace:548 print((" --- modulename: %s, funcname: %s"549 % (modulename, code.co_name)))550 return self.localtrace551 else:552 return None553 554 def localtrace_trace_and_count(self, frame, why, arg):555 if why == "line":556 # record the file name and line number of every trace557 filename = frame.f_code.co_filename558 lineno = frame.f_lineno559 key = filename, lineno560 self.counts[key] = self.counts.get(key, 0) + 1561 562 if self.start_time:563 print('%.2f' % (_time() - self.start_time), end=' ')564 bname = os.path.basename(filename)565 line = linecache.getline(filename, lineno)566 print("%s(%d)" % (bname, lineno), end='')567 if line:568 print(": ", line, end='')569 else:570 print()571 return self.localtrace572 573 def localtrace_trace(self, frame, why, arg):574 if why == "line":575 # record the file name and line number of every trace576 filename = frame.f_code.co_filename577 lineno = frame.f_lineno578 579 if self.start_time:580 print('%.2f' % (_time() - self.start_time), end=' ')581 bname = os.path.basename(filename)582 line = linecache.getline(filename, lineno)583 print("%s(%d)" % (bname, lineno), end='')584 if line:585 print(": ", line, end='')586 else:587 print()588 return self.localtrace589 590 def localtrace_count(self, frame, why, arg):591 if why == "line":592 filename = frame.f_code.co_filename593 lineno = frame.f_lineno594 key = filename, lineno595 self.counts[key] = self.counts.get(key, 0) + 1596 return self.localtrace597 598 def results(self):599 return CoverageResults(self.counts, infile=self.infile,600 outfile=self.outfile,601 calledfuncs=self._calledfuncs,602 callers=self._callers)603 604def main():605 import argparse606 607 parser = argparse.ArgumentParser(color=True)608 parser.add_argument('--version', action='version', version='trace 2.0')609 610 grp = parser.add_argument_group('Main options',611 'One of these (or --report) must be given')612 613 grp.add_argument('-c', '--count', action='store_true',614 help='Count the number of times each line is executed and write '615 'the counts to <module>.cover for each module executed, in '616 'the module\'s directory. See also --coverdir, --file, '617 '--no-report below.')618 grp.add_argument('-t', '--trace', action='store_true',619 help='Print each line to sys.stdout before it is executed')620 grp.add_argument('-l', '--listfuncs', action='store_true',621 help='Keep track of which functions are executed at least once '622 'and write the results to sys.stdout after the program exits. '623 'Cannot be specified alongside --trace or --count.')624 grp.add_argument('-T', '--trackcalls', action='store_true',625 help='Keep track of caller/called pairs and write the results to '626 'sys.stdout after the program exits.')627 628 grp = parser.add_argument_group('Modifiers')629 630 _grp = grp.add_mutually_exclusive_group()631 _grp.add_argument('-r', '--report', action='store_true',632 help='Generate a report from a counts file; does not execute any '633 'code. --file must specify the results file to read, which '634 'must have been created in a previous run with --count '635 '--file=FILE')636 _grp.add_argument('-R', '--no-report', action='store_true',637 help='Do not generate the coverage report files. '638 'Useful if you want to accumulate over several runs.')639 640 grp.add_argument('-f', '--file',641 help='File to accumulate counts over several runs')642 grp.add_argument('-C', '--coverdir',643 help='Directory where the report files go. The coverage report '644 'for <package>.<module> will be written to file '645 '<dir>/<package>/<module>.cover')646 grp.add_argument('-m', '--missing', action='store_true',647 help='Annotate executable lines that were not executed with '648 '">>>>>> "')649 grp.add_argument('-s', '--summary', action='store_true',650 help='Write a brief summary for each file to sys.stdout. '651 'Can only be used with --count or --report')652 grp.add_argument('-g', '--timing', action='store_true',653 help='Prefix each line with the time since the program started. '654 'Only used while tracing')655 656 grp = parser.add_argument_group('Filters',657 'Can be specified multiple times')658 grp.add_argument('--ignore-module', action='append', default=[],659 help='Ignore the given module(s) and its submodules '660 '(if it is a package). Accepts comma separated list of '661 'module names.')662 grp.add_argument('--ignore-dir', action='append', default=[],663 help='Ignore files in the given directory '664 '(multiple directories can be joined by os.pathsep).')665 666 parser.add_argument('--module', action='store_true', default=False,667 help='Trace a module. ')668 parser.add_argument('progname', nargs='?',669 help='file to run as main program')670 parser.add_argument('arguments', nargs=argparse.REMAINDER,671 help='arguments to the program')672 673 opts = parser.parse_args()674 675 if opts.ignore_dir:676 _prefix = sysconfig.get_path("stdlib")677 _exec_prefix = sysconfig.get_path("platstdlib")678 679 def parse_ignore_dir(s):680 s = os.path.expanduser(os.path.expandvars(s))681 s = s.replace('$prefix', _prefix).replace('$exec_prefix', _exec_prefix)682 return os.path.normpath(s)683 684 opts.ignore_module = [mod.strip()685 for i in opts.ignore_module for mod in i.split(',')]686 opts.ignore_dir = [parse_ignore_dir(s)687 for i in opts.ignore_dir for s in i.split(os.pathsep)]688 689 if opts.report:690 if not opts.file:691 parser.error('-r/--report requires -f/--file')692 results = CoverageResults(infile=opts.file, outfile=opts.file)693 return results.write_results(opts.missing, opts.summary, opts.coverdir)694 695 if not any([opts.trace, opts.count, opts.listfuncs, opts.trackcalls]):696 parser.error('must specify one of --trace, --count, --report, '697 '--listfuncs, or --trackcalls')698 699 if opts.listfuncs and (opts.count or opts.trace):700 parser.error('cannot specify both --listfuncs and (--trace or --count)')701 702 if opts.summary and not opts.count:703 parser.error('--summary can only be used with --count or --report')704 705 if opts.progname is None:706 parser.error('progname is missing: required with the main options')707 708 t = Trace(opts.count, opts.trace, countfuncs=opts.listfuncs,709 countcallers=opts.trackcalls, ignoremods=opts.ignore_module,710 ignoredirs=opts.ignore_dir, infile=opts.file,711 outfile=opts.file, timing=opts.timing)712 try:713 if opts.module:714 import runpy715 module_name = opts.progname716 mod_name, mod_spec, code = runpy._get_module_details(module_name)717 sys.argv = [code.co_filename, *opts.arguments]718 globs = {719 '__name__': '__main__',720 '__file__': code.co_filename,721 '__package__': mod_spec.parent,722 '__loader__': mod_spec.loader,723 '__spec__': mod_spec,724 '__cached__': None,725 }726 else:727 sys.argv = [opts.progname, *opts.arguments]728 sys.path[0] = os.path.dirname(opts.progname)729 730 with io.open_code(opts.progname) as fp:731 code = compile(fp.read(), opts.progname, 'exec')732 # try to emulate __main__ namespace as much as possible733 globs = {734 '__file__': opts.progname,735 '__name__': '__main__',736 '__package__': None,737 '__cached__': None,738 }739 t.runctx(code, globs, globs)740 except OSError as err:741 sys.exit("Cannot run file %r because: %s" % (sys.argv[0], err))742 except SystemExit:743 pass744 745 results = t.results()746 747 if not opts.no_report:748 results.write_results(opts.missing, opts.summary, opts.coverdir)749 750if __name__=='__main__':751 main()752