3 # portions copyright 2001, Autonomous Zones Industries, Inc., all rights...
4 # err... reserved and offered to the public under the terms of the
6 # Author: Zooko O'Whielacronx
8 # mailto:zooko@zooko.com
10 # Copyright 2000, Mojam Media, Inc., all rights reserved.
11 # Author: Skip Montanaro
13 # Copyright 1999, Bioreason, Inc., all rights reserved.
14 # Author: Andrew Dalke
16 # Copyright 1995-1997, Automatrix, Inc., all rights reserved.
17 # Author: Skip Montanaro
19 # Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.
22 # Permission to use, copy, modify, and distribute this Python software and
23 # its associated documentation for any purpose without fee is hereby
24 # granted, provided that the above copyright notice appears in all copies,
25 # and that both that copyright notice and this permission notice appear in
26 # supporting documentation, and that the name of neither Automatrix,
27 # Bioreason or Mojam Media be used in advertising or publicity pertaining to
28 # distribution of the software without specific, written prior permission.
30 """program/module to trace Python program or function execution
32 Sample use, command line:
33 trace.py -c -f counts --ignore-dir '$prefix' spam.py eggs
34 trace.py -t --ignore-dir '$prefix' spam.py eggs
35 trace.py --trackcalls spam.py eggs
37 Sample use, programmatically
40 # create a Trace object, telling it what to ignore, and whether to
41 # do tracing or line-counting or both.
42 tracer = trace.Trace(ignoredirs=[sys.prefix, sys.exec_prefix,], trace=0,
44 # run the new command using the given tracer
46 # make a report, placing output in /tmp
48 r.write_results(show_missing=True, coverdir="/tmp")
68 outfile
.write("""Usage: %s [OPTIONS] <file> [ARGS]
71 --help Display this help then exit.
72 --version Output version information then exit.
74 Otherwise, exactly one of the following three options must be given:
75 -t, --trace Print each line to sys.stdout before it is executed.
76 -c, --count Count the number of times each line is executed
77 and write the counts to <module>.cover for each
78 module executed, in the module's directory.
79 See also `--coverdir', `--file', `--no-report' below.
80 -l, --listfuncs Keep track of which functions are executed at least
81 once and write the results to sys.stdout after the
83 -T, --trackcalls Keep track of caller/called pairs and write the
84 results to sys.stdout after the program exits.
85 -r, --report Generate a report from a counts file; do not execute
86 any code. `--file' must specify the results file to
87 read, which must have been created in a previous run
88 with `--count --file=FILE'.
91 -f, --file=<file> File to accumulate counts over several runs.
92 -R, --no-report Do not generate the coverage report files.
93 Useful if you want to accumulate over several runs.
94 -C, --coverdir=<dir> Directory where the report files. The coverage
95 report for <package>.<module> is written to file
96 <dir>/<package>/<module>.cover.
97 -m, --missing Annotate executable lines that were not executed
99 -s, --summary Write a brief summary on stdout for each file.
100 (Can only be used with --count or --report.)
102 Filters, may be repeated multiple times:
103 --ignore-module=<mod> Ignore the given module and its submodules
104 (if it is a package).
105 --ignore-dir=<dir> Ignore files in the given directory (multiple
106 directories can be joined by os.pathsep).
109 PRAGMA_NOCOVER
= "#pragma NO COVER"
111 # Simple rx to find lines with no code.
112 rx_blank
= re
.compile(r
'^\s*(#.*)?$')
115 def __init__(self
, modules
= None, dirs
= None):
116 self
._mods
= modules
or []
117 self
._dirs
= dirs
or []
119 self
._dirs
= map(os
.path
.normpath
, self
._dirs
)
120 self
._ignore
= { '<string>': 1 }
122 def names(self
, filename
, modulename
):
123 if self
._ignore
.has_key(modulename
):
124 return self
._ignore
[modulename
]
126 # haven't seen this one before, so see if the module name is
127 # on the ignore list. Need to take some care since ignoring
128 # "cmp" musn't mean ignoring "cmpcache" but ignoring
129 # "Spam" must also mean ignoring "Spam.Eggs".
130 for mod
in self
._mods
:
131 if mod
== modulename
: # Identical names, so ignore
132 self
._ignore
[modulename
] = 1
134 # check if the module is a proper submodule of something on
137 # (will not overflow since if the first n characters are the
138 # same and the name has not already occurred, then the size
139 # of "name" is greater than that of "mod")
140 if mod
== modulename
[:n
] and modulename
[n
] == '.':
141 self
._ignore
[modulename
] = 1
144 # Now check that __file__ isn't in one of the directories
146 # must be a built-in, so we must ignore
147 self
._ignore
[modulename
] = 1
150 # Ignore a file when it contains one of the ignorable paths
152 # The '+ os.sep' is to ensure that d is a parent directory,
153 # as compared to cases like:
155 # filename = "/usr/local.py"
157 # d = "/usr/local.py"
158 # filename = "/usr/local.py"
159 if filename
.startswith(d
+ os
.sep
):
160 self
._ignore
[modulename
] = 1
163 # Tried the different ways, so we don't ignore this module
164 self
._ignore
[modulename
] = 0
168 """Return a plausible module name for the patch."""
170 base
= os
.path
.basename(path
)
171 filename
, ext
= os
.path
.splitext(base
)
174 def fullmodname(path
):
175 """Return a plausible module name for the path."""
177 # If the file 'path' is part of a package, then the filename isn't
178 # enough to uniquely identify it. Try to do the right thing by
179 # looking in sys.path for the longest matching prefix. We'll
180 # assume that the rest is the package name.
182 comparepath
= os
.path
.normcase(path
)
185 dir = os
.path
.normcase(dir)
186 if comparepath
.startswith(dir) and comparepath
[len(dir)] == os
.sep
:
187 if len(dir) > len(longest
):
191 base
= path
[len(longest
) + 1:]
194 base
= base
.replace(os
.sep
, ".")
196 base
= base
.replace(os
.altsep
, ".")
197 filename
, ext
= os
.path
.splitext(base
)
200 class CoverageResults
:
201 def __init__(self
, counts
=None, calledfuncs
=None, infile
=None,
202 callers
=None, outfile
=None):
204 if self
.counts
is None:
206 self
.counter
= self
.counts
.copy() # map (filename, lineno) to count
207 self
.calledfuncs
= calledfuncs
208 if self
.calledfuncs
is None:
209 self
.calledfuncs
= {}
210 self
.calledfuncs
= self
.calledfuncs
.copy()
211 self
.callers
= callers
212 if self
.callers
is None:
214 self
.callers
= self
.callers
.copy()
216 self
.outfile
= outfile
218 # Try to merge existing counts file.
220 counts
, calledfuncs
, callers
= \
221 pickle
.load(open(self
.infile
, 'rb'))
222 self
.update(self
.__class
__(counts
, calledfuncs
, callers
))
223 except (IOError, EOFError, ValueError), err
:
224 print >> sys
.stderr
, ("Skipping counts file %r: %s"
225 % (self
.infile
, err
))
227 def update(self
, other
):
228 """Merge in the data from another CoverageResults"""
230 calledfuncs
= self
.calledfuncs
231 callers
= self
.callers
232 other_counts
= other
.counts
233 other_calledfuncs
= other
.calledfuncs
234 other_callers
= other
.callers
236 for key
in other_counts
.keys():
237 counts
[key
] = counts
.get(key
, 0) + other_counts
[key
]
239 for key
in other_calledfuncs
.keys():
242 for key
in other_callers
.keys():
245 def write_results(self
, show_missing
=True, summary
=False, coverdir
=None):
251 print "functions called:"
252 calls
= self
.calledfuncs
.keys()
254 for filename
, modulename
, funcname
in calls
:
255 print ("filename: %s, modulename: %s, funcname: %s"
256 % (filename
, modulename
, funcname
))
260 print "calling relationships:"
261 calls
= self
.callers
.keys()
263 lastfile
= lastcfile
= ""
264 for ((pfile
, pmod
, pfunc
), (cfile
, cmod
, cfunc
)) in calls
:
265 if pfile
!= lastfile
:
267 print "***", pfile
, "***"
270 if cfile
!= pfile
and lastcfile
!= cfile
:
273 print " %s.%s -> %s.%s" % (pmod
, pfunc
, cmod
, cfunc
)
275 # turn the counts data ("(filename, lineno) = count") into something
276 # accessible on a per-file basis
278 for filename
, lineno
in self
.counts
.keys():
279 lines_hit
= per_file
[filename
] = per_file
.get(filename
, {})
280 lines_hit
[lineno
] = self
.counts
[(filename
, lineno
)]
282 # accumulate summary info, if needed
285 for filename
, count
in per_file
.iteritems():
286 # skip some "files" we don't care about...
287 if filename
== "<string>":
290 if filename
.endswith((".pyc", ".pyo")):
291 filename
= filename
[:-1]
294 dir = os
.path
.dirname(os
.path
.abspath(filename
))
295 modulename
= modname(filename
)
298 if not os
.path
.exists(dir):
300 modulename
= fullmodname(filename
)
302 # If desired, get a list of the line numbers which represent
303 # executable content (returned as a dict for better lookup speed)
305 lnotab
= find_executable_linenos(filename
)
309 source
= linecache
.getlines(filename
)
310 coverpath
= os
.path
.join(dir, modulename
+ ".cover")
311 n_hits
, n_lines
= self
.write_results_file(coverpath
, source
,
314 if summary
and n_lines
:
315 percent
= int(100 * n_hits
/ n_lines
)
316 sums
[modulename
] = n_lines
, percent
, modulename
, filename
321 print "lines cov% module (path)"
323 n_lines
, percent
, modulename
, filename
= sums
[m
]
324 print "%5d %3d%% %s (%s)" % sums
[m
]
327 # try and store counts and module info into self.outfile
329 pickle
.dump((self
.counts
, self
.calledfuncs
, self
.callers
),
330 open(self
.outfile
, 'wb'), 1)
332 print >> sys
.stderr
, "Can't save counts files because %s" % err
334 def write_results_file(self
, path
, lines
, lnotab
, lines_hit
):
335 """Return a coverage results file in path."""
338 outfile
= open(path
, "w")
340 print >> sys
.stderr
, ("trace: Could not open %r for writing: %s"
341 "- skipping" % (path
, err
))
346 for i
, line
in enumerate(lines
):
348 # do the blank/comment match to try to mark more lines
349 # (help the reader find stuff that hasn't been covered)
350 if lineno
in lines_hit
:
351 outfile
.write("%5d: " % lines_hit
[lineno
])
354 elif rx_blank
.match(line
):
357 # lines preceded by no marks weren't hit
358 # Highlight them if so indicated, unless the line contains
360 if lineno
in lnotab
and not PRAGMA_NOCOVER
in lines
[i
]:
361 outfile
.write(">>>>>> ")
365 outfile
.write(lines
[i
].expandtabs(8))
368 return n_hits
, n_lines
370 def find_lines_from_code(code
, strs
):
371 """Return dict where keys are lines in the line number table."""
374 line_increments
= [ord(c
) for c
in code
.co_lnotab
[1::2]]
375 table_length
= len(line_increments
)
378 lineno
= code
.co_firstlineno
379 for li
in line_increments
:
381 if lineno
not in strs
:
386 def find_lines(code
, strs
):
387 """Return lineno dict for all code objects reachable from code."""
388 # get all of the lineno information from the code of this scope level
389 linenos
= find_lines_from_code(code
, strs
)
391 # and check the constants for references to other code objects
392 for c
in code
.co_consts
:
393 if isinstance(c
, types
.CodeType
):
394 # find another code object, so recurse into it
395 linenos
.update(find_lines(c
, strs
))
398 def find_strings(filename
):
399 """Return a dict of possible docstring positions.
401 The dict maps line numbers to strings. There is an entry for
402 line that contains only a string or a part of a triple-quoted
406 # If the first token is a string, then it's the module docstring.
407 # Add this special case so that the test in the loop passes.
408 prev_ttype
= token
.INDENT
410 for ttype
, tstr
, start
, end
, line
in tokenize
.generate_tokens(f
.readline
):
411 if ttype
== token
.STRING
:
412 if prev_ttype
== token
.INDENT
:
415 for i
in range(sline
, eline
+ 1):
421 def find_executable_linenos(filename
):
422 """Return dict where keys are line numbers in the line number table."""
424 prog
= open(filename
, "rU").read()
426 print >> sys
.stderr
, ("Not printing coverage data for %r: %s"
429 code
= compile(prog
, filename
, "exec")
430 strs
= find_strings(filename
)
431 return find_lines(code
, strs
)
434 def __init__(self
, count
=1, trace
=1, countfuncs
=0, countcallers
=0,
435 ignoremods
=(), ignoredirs
=(), infile
=None, outfile
=None):
437 @param count true iff it should count number of times each
439 @param trace true iff it should print out each line that is
441 @param countfuncs true iff it should just output a list of
442 (filename, modulename, funcname,) for functions
443 that were called at least once; This overrides
445 @param ignoremods a list of the names of modules to ignore
446 @param ignoredirs a list of the names of directories to ignore
447 all of the (recursive) contents of
448 @param infile file from which to read stored counts to be
449 added into the results
450 @param outfile file in which to write the results
453 self
.outfile
= outfile
454 self
.ignore
= Ignore(ignoremods
, ignoredirs
)
455 self
.counts
= {} # keys are (filename, linenumber)
456 self
.blabbed
= {} # for debugging
457 self
.pathtobasename
= {} # for memoizing os.path.basename
460 self
._calledfuncs
= {}
462 self
._caller
_cache
= {}
464 self
.globaltrace
= self
.globaltrace_trackcallers
466 self
.globaltrace
= self
.globaltrace_countfuncs
467 elif trace
and count
:
468 self
.globaltrace
= self
.globaltrace_lt
469 self
.localtrace
= self
.localtrace_trace_and_count
471 self
.globaltrace
= self
.globaltrace_lt
472 self
.localtrace
= self
.localtrace_trace
474 self
.globaltrace
= self
.globaltrace_lt
475 self
.localtrace
= self
.localtrace_count
477 # Ahem -- do nothing? Okay.
482 dict = __main__
.__dict
__
483 if not self
.donothing
:
484 sys
.settrace(self
.globaltrace
)
485 threading
.settrace(self
.globaltrace
)
487 exec cmd
in dict, dict
489 if not self
.donothing
:
491 threading
.settrace(None)
493 def runctx(self
, cmd
, globals=None, locals=None):
494 if globals is None: globals = {}
495 if locals is None: locals = {}
496 if not self
.donothing
:
497 sys
.settrace(self
.globaltrace
)
498 threading
.settrace(self
.globaltrace
)
500 exec cmd
in globals, locals
502 if not self
.donothing
:
504 threading
.settrace(None)
506 def runfunc(self
, func
, *args
, **kw
):
508 if not self
.donothing
:
509 sys
.settrace(self
.globaltrace
)
511 result
= func(*args
, **kw
)
513 if not self
.donothing
:
517 def file_module_function_of(self
, frame
):
519 filename
= code
.co_filename
521 modulename
= modname(filename
)
525 funcname
= code
.co_name
527 if code
in self
._caller
_cache
:
528 if self
._caller
_cache
[code
] is not None:
529 clsname
= self
._caller
_cache
[code
]
531 self
._caller
_cache
[code
] = None
532 ## use of gc.get_referrers() was suggested by Michael Hudson
533 # all functions which refer to this code object
534 funcs
= [f
for f
in gc
.get_referrers(code
)
535 if hasattr(f
, "func_doc")]
536 # require len(func) == 1 to avoid ambiguity caused by calls to
537 # new.function(): "In the face of ambiguity, refuse the
538 # temptation to guess."
540 dicts
= [d
for d
in gc
.get_referrers(funcs
[0])
541 if isinstance(d
, dict)]
543 classes
= [c
for c
in gc
.get_referrers(dicts
[0])
544 if hasattr(c
, "__bases__")]
545 if len(classes
) == 1:
546 # ditto for new.classobj()
547 clsname
= str(classes
[0])
548 # cache the result - assumption is that new.* is
549 # not called later to disturb this relationship
550 # _caller_cache could be flushed if functions in
551 # the new module get called.
552 self
._caller
_cache
[code
] = clsname
553 if clsname
is not None:
554 # final hack - module name shows up in str(cls), but we've already
555 # computed module name, so remove it
556 clsname
= clsname
.split(".")[1:]
557 clsname
= ".".join(clsname
)
558 funcname
= "%s.%s" % (clsname
, funcname
)
560 return filename
, modulename
, funcname
562 def globaltrace_trackcallers(self
, frame
, why
, arg
):
563 """Handler for call events.
565 Adds information about who called who to the self._callers dict.
568 # XXX Should do a better job of identifying methods
569 this_func
= self
.file_module_function_of(frame
)
570 parent_func
= self
.file_module_function_of(frame
.f_back
)
571 self
._callers
[(parent_func
, this_func
)] = 1
573 def globaltrace_countfuncs(self
, frame
, why
, arg
):
574 """Handler for call events.
576 Adds (filename, modulename, funcname) to the self._calledfuncs dict.
579 this_func
= self
.file_module_function_of(frame
)
580 self
._calledfuncs
[this_func
] = 1
582 def globaltrace_lt(self
, frame
, why
, arg
):
583 """Handler for call events.
585 If the code block being entered is to be ignored, returns `None',
586 else returns self.localtrace.
590 filename
= code
.co_filename
592 # XXX modname() doesn't work right for packages, so
593 # the ignore support won't work right for packages
594 modulename
= modname(filename
)
595 if modulename
is not None:
596 ignore_it
= self
.ignore
.names(filename
, modulename
)
599 print (" --- modulename: %s, funcname: %s"
600 % (modulename
, code
.co_name
))
601 return self
.localtrace
605 def localtrace_trace_and_count(self
, frame
, why
, arg
):
607 # record the file name and line number of every trace
608 filename
= frame
.f_code
.co_filename
609 lineno
= frame
.f_lineno
610 key
= filename
, lineno
611 self
.counts
[key
] = self
.counts
.get(key
, 0) + 1
613 bname
= os
.path
.basename(filename
)
614 print "%s(%d): %s" % (bname
, lineno
,
615 linecache
.getline(filename
, lineno
)),
616 return self
.localtrace
618 def localtrace_trace(self
, frame
, why
, arg
):
620 # record the file name and line number of every trace
621 filename
= frame
.f_code
.co_filename
622 lineno
= frame
.f_lineno
624 bname
= os
.path
.basename(filename
)
625 print "%s(%d): %s" % (bname
, lineno
,
626 linecache
.getline(filename
, lineno
)),
627 return self
.localtrace
629 def localtrace_count(self
, frame
, why
, arg
):
631 filename
= frame
.f_code
.co_filename
632 lineno
= frame
.f_lineno
633 key
= filename
, lineno
634 self
.counts
[key
] = self
.counts
.get(key
, 0) + 1
635 return self
.localtrace
638 return CoverageResults(self
.counts
, infile
=self
.infile
,
639 outfile
=self
.outfile
,
640 calledfuncs
=self
._calledfuncs
,
641 callers
=self
._callers
)
644 sys
.stderr
.write("%s: %s\n" % (sys
.argv
[0], msg
))
653 opts
, prog_argv
= getopt
.getopt(argv
[1:], "tcrRf:d:msC:lT",
654 ["help", "version", "trace", "count",
655 "report", "no-report", "summary",
657 "ignore-module=", "ignore-dir=",
658 "coverdir=", "listfuncs",
661 except getopt
.error
, msg
:
662 sys
.stderr
.write("%s: %s\n" % (sys
.argv
[0], msg
))
663 sys
.stderr
.write("Try `%s --help' for more information\n"
680 for opt
, val
in opts
:
685 if opt
== "--version":
686 sys
.stdout
.write("trace 2.0\n")
689 if opt
== "-T" or opt
== "--trackcalls":
693 if opt
== "-l" or opt
== "--listfuncs":
697 if opt
== "-t" or opt
== "--trace":
701 if opt
== "-c" or opt
== "--count":
705 if opt
== "-r" or opt
== "--report":
709 if opt
== "-R" or opt
== "--no-report":
713 if opt
== "-f" or opt
== "--file":
717 if opt
== "-m" or opt
== "--missing":
721 if opt
== "-C" or opt
== "--coverdir":
725 if opt
== "-s" or opt
== "--summary":
729 if opt
== "--ignore-module":
730 ignore_modules
.append(val
)
733 if opt
== "--ignore-dir":
734 for s
in val
.split(os
.pathsep
):
735 s
= os
.path
.expandvars(s
)
736 # should I also call expanduser? (after all, could use $HOME)
738 s
= s
.replace("$prefix",
739 os
.path
.join(sys
.prefix
, "lib",
740 "python" + sys
.version
[:3]))
741 s
= s
.replace("$exec_prefix",
742 os
.path
.join(sys
.exec_prefix
, "lib",
743 "python" + sys
.version
[:3]))
744 s
= os
.path
.normpath(s
)
745 ignore_dirs
.append(s
)
748 assert 0, "Should never get here"
750 if listfuncs
and (count
or trace
):
751 _err_exit("cannot specify both --listfuncs and (--trace or --count)")
753 if not (count
or trace
or report
or listfuncs
or countcallers
):
754 _err_exit("must specify one of --trace, --count, --report, "
755 "--listfuncs, or --trackcalls")
757 if report
and no_report
:
758 _err_exit("cannot specify both --report and --no-report")
760 if report
and not counts_file
:
761 _err_exit("--report requires a --file")
763 if no_report
and len(prog_argv
) == 0:
764 _err_exit("missing name of file to run")
766 # everything is ready
768 results
= CoverageResults(infile
=counts_file
, outfile
=counts_file
)
769 results
.write_results(missing
, summary
=summary
, coverdir
=coverdir
)
772 progname
= prog_argv
[0]
773 sys
.path
[0] = os
.path
.split(progname
)[0]
775 t
= Trace(count
, trace
, countfuncs
=listfuncs
,
776 countcallers
=countcallers
, ignoremods
=ignore_modules
,
777 ignoredirs
=ignore_dirs
, infile
=counts_file
,
780 t
.run('execfile(%r)' % (progname
,))
782 _err_exit("Cannot run file %r because: %s" % (sys
.argv
[0], err
))
786 results
= t
.results()
789 results
.write_results(missing
, summary
=summary
, coverdir
=coverdir
)
791 if __name__
=='__main__':