blob: 53c6150fd406c99e95f01e7b2df16db1c1f6d225 [file] [log] [blame]
Benjamin Peterson90f5ba52010-03-11 22:53:45 +00001#!/usr/bin/env python3
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +00002
3# portions copyright 2001, Autonomous Zones Industries, Inc., all rights...
4# err... reserved and offered to the public under the terms of the
5# Python 2.2 license.
6# Author: Zooko O'Whielacronx
7# http://zooko.com/
8# mailto:zooko@zooko.com
9#
10# Copyright 2000, Mojam Media, Inc., all rights reserved.
11# Author: Skip Montanaro
12#
13# Copyright 1999, Bioreason, Inc., all rights reserved.
14# Author: Andrew Dalke
15#
16# Copyright 1995-1997, Automatrix, Inc., all rights reserved.
17# Author: Skip Montanaro
18#
19# Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.
20#
21#
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.
29#
30"""program/module to trace Python program or function execution
31
32Sample 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
Skip Montanaro5bfd9842004-04-10 16:29:58 +000035 trace.py --trackcalls spam.py eggs
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +000036
37Sample use, programmatically
Thomas Wouters477c8d52006-05-27 19:21:47 +000038 import sys
39
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,
43 count=1)
44 # run the new command using the given tracer
45 tracer.run('main()')
46 # make a report, placing output in /tmp
47 r = tracer.results()
48 r.write_results(show_missing=True, coverdir="/tmp")
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +000049"""
Alexander Belopolsky44454af2010-11-20 18:21:07 +000050__all__ = ['Trace', 'CoverageResults']
Georg Brandl33c28812009-04-01 23:07:29 +000051import io
Jeremy Hylton38732e12003-04-21 22:04:46 +000052import linecache
Jeremy Hylton38732e12003-04-21 22:04:46 +000053import os
54import re
55import sys
Christian Heimes380f7f22008-02-28 11:19:05 +000056import time
Jeremy Hylton38732e12003-04-21 22:04:46 +000057import token
58import tokenize
Alexander Belopolsky4d770172010-09-13 18:14:34 +000059import inspect
Skip Montanaro5bfd9842004-04-10 16:29:58 +000060import gc
Alexander Belopolskyff09ce22010-09-24 18:03:12 +000061import dis
Guido van Rossum99603b02007-07-20 00:22:32 +000062import pickle
Alexander Belopolsky44454af2010-11-20 18:21:07 +000063from warnings import warn as _warn
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +000064
Alexander Belopolsky25b57412010-11-06 01:31:16 +000065try:
66 import threading
67except ImportError:
68 _settrace = sys.settrace
69
70 def _unsettrace():
71 sys.settrace(None)
72else:
73 def _settrace(func):
74 threading.settrace(func)
75 sys.settrace(func)
76
77 def _unsettrace():
78 sys.settrace(None)
79 threading.settrace(None)
80
Alexander Belopolsky44454af2010-11-20 18:21:07 +000081def _usage(outfile):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +000082 outfile.write("""Usage: %s [OPTIONS] <file> [ARGS]
83
84Meta-options:
85--help Display this help then exit.
86--version Output version information then exit.
87
88Otherwise, exactly one of the following three options must be given:
89-t, --trace Print each line to sys.stdout before it is executed.
90-c, --count Count the number of times each line is executed
91 and write the counts to <module>.cover for each
92 module executed, in the module's directory.
93 See also `--coverdir', `--file', `--no-report' below.
Skip Montanaroa7b8ac62003-06-27 19:09:33 +000094-l, --listfuncs Keep track of which functions are executed at least
Fred Drake01c623b2003-06-27 19:22:11 +000095 once and write the results to sys.stdout after the
Skip Montanaroa7b8ac62003-06-27 19:09:33 +000096 program exits.
Skip Montanarocafc8112004-04-07 15:46:05 +000097-T, --trackcalls Keep track of caller/called pairs and write the
98 results to sys.stdout after the program exits.
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +000099-r, --report Generate a report from a counts file; do not execute
100 any code. `--file' must specify the results file to
101 read, which must have been created in a previous run
102 with `--count --file=FILE'.
103
104Modifiers:
105-f, --file=<file> File to accumulate counts over several runs.
106-R, --no-report Do not generate the coverage report files.
107 Useful if you want to accumulate over several runs.
108-C, --coverdir=<dir> Directory where the report files. The coverage
109 report for <package>.<module> is written to file
110 <dir>/<package>/<module>.cover.
111-m, --missing Annotate executable lines that were not executed
112 with '>>>>>> '.
113-s, --summary Write a brief summary on stdout for each file.
114 (Can only be used with --count or --report.)
Christian Heimes380f7f22008-02-28 11:19:05 +0000115-g, --timing Prefix each line with the time since the program started.
116 Only used while tracing.
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000117
118Filters, may be repeated multiple times:
Georg Brandlfceab5a2008-01-19 20:08:23 +0000119--ignore-module=<mod> Ignore the given module(s) and its submodules
120 (if it is a package). Accepts comma separated
121 list of module names
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000122--ignore-dir=<dir> Ignore files in the given directory (multiple
123 directories can be joined by os.pathsep).
124""" % sys.argv[0])
125
Jeremy Hylton38732e12003-04-21 22:04:46 +0000126PRAGMA_NOCOVER = "#pragma NO COVER"
127
128# Simple rx to find lines with no code.
129rx_blank = re.compile(r'^\s*(#.*)?$')
130
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000131class _Ignore:
Alexander Belopolsky6672ea92010-11-08 18:32:40 +0000132 def __init__(self, modules=None, dirs=None):
133 self._mods = set() if not modules else set(modules)
134 self._dirs = [] if not dirs else [os.path.normpath(d)
135 for d in dirs]
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000136 self._ignore = { '<string>': 1 }
137
138 def names(self, filename, modulename):
Guido van Rossume2b70bc2006-08-18 22:13:04 +0000139 if modulename in self._ignore:
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000140 return self._ignore[modulename]
141
142 # haven't seen this one before, so see if the module name is
Alexander Belopolsky6672ea92010-11-08 18:32:40 +0000143 # on the ignore list.
144 if modulename in self._mods: # Identical names, so ignore
145 self._ignore[modulename] = 1
146 return 1
147
148 # check if the module is a proper submodule of something on
149 # the ignore list
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000150 for mod in self._mods:
Alexander Belopolsky6672ea92010-11-08 18:32:40 +0000151 # Need to take some care since ignoring
152 # "cmp" mustn't mean ignoring "cmpcache" but ignoring
153 # "Spam" must also mean ignoring "Spam.Eggs".
154 if modulename.startswith(mod + '.'):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000155 self._ignore[modulename] = 1
156 return 1
157
Alexander Belopolsky6672ea92010-11-08 18:32:40 +0000158 # Now check that filename isn't in one of the directories
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000159 if filename is None:
160 # must be a built-in, so we must ignore
161 self._ignore[modulename] = 1
162 return 1
163
164 # Ignore a file when it contains one of the ignorable paths
165 for d in self._dirs:
166 # The '+ os.sep' is to ensure that d is a parent directory,
167 # as compared to cases like:
168 # d = "/usr/local"
169 # filename = "/usr/local.py"
170 # or
171 # d = "/usr/local.py"
172 # filename = "/usr/local.py"
173 if filename.startswith(d + os.sep):
174 self._ignore[modulename] = 1
175 return 1
176
177 # Tried the different ways, so we don't ignore this module
178 self._ignore[modulename] = 0
179 return 0
180
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000181def _modname(path):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000182 """Return a plausible module name for the patch."""
Jeremy Hyltondfbfe732003-04-21 22:49:17 +0000183
Jeremy Hylton38732e12003-04-21 22:04:46 +0000184 base = os.path.basename(path)
185 filename, ext = os.path.splitext(base)
186 return filename
187
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000188def _fullmodname(path):
Jeremy Hyltonc8c8b942003-04-22 15:35:51 +0000189 """Return a plausible module name for the path."""
Jeremy Hyltondfbfe732003-04-21 22:49:17 +0000190
191 # If the file 'path' is part of a package, then the filename isn't
192 # enough to uniquely identify it. Try to do the right thing by
193 # looking in sys.path for the longest matching prefix. We'll
194 # assume that the rest is the package name.
195
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000196 comparepath = os.path.normcase(path)
Jeremy Hyltondfbfe732003-04-21 22:49:17 +0000197 longest = ""
198 for dir in sys.path:
Thomas Wouters00ee7ba2006-08-21 19:07:27 +0000199 dir = os.path.normcase(dir)
200 if comparepath.startswith(dir) and comparepath[len(dir)] == os.sep:
Jeremy Hyltondfbfe732003-04-21 22:49:17 +0000201 if len(dir) > len(longest):
202 longest = dir
203
Guido van Rossumb427c002003-10-10 23:02:01 +0000204 if longest:
205 base = path[len(longest) + 1:]
206 else:
207 base = path
Georg Brandl120d6332010-08-01 14:38:17 +0000208 # the drive letter is never part of the module name
209 drive, base = os.path.splitdrive(base)
Guido van Rossumbbca8da2004-02-19 19:16:50 +0000210 base = base.replace(os.sep, ".")
211 if os.altsep:
212 base = base.replace(os.altsep, ".")
Jeremy Hyltondfbfe732003-04-21 22:49:17 +0000213 filename, ext = os.path.splitext(base)
Georg Brandl120d6332010-08-01 14:38:17 +0000214 return filename.lstrip(".")
Jeremy Hyltondfbfe732003-04-21 22:49:17 +0000215
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000216class CoverageResults:
217 def __init__(self, counts=None, calledfuncs=None, infile=None,
Skip Montanarocafc8112004-04-07 15:46:05 +0000218 callers=None, outfile=None):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000219 self.counts = counts
220 if self.counts is None:
221 self.counts = {}
222 self.counter = self.counts.copy() # map (filename, lineno) to count
223 self.calledfuncs = calledfuncs
224 if self.calledfuncs is None:
225 self.calledfuncs = {}
226 self.calledfuncs = self.calledfuncs.copy()
Skip Montanarocafc8112004-04-07 15:46:05 +0000227 self.callers = callers
228 if self.callers is None:
229 self.callers = {}
230 self.callers = self.callers.copy()
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000231 self.infile = infile
232 self.outfile = outfile
233 if self.infile:
Jeremy Hyltond7ce86d2003-07-07 16:08:47 +0000234 # Try to merge existing counts file.
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000235 try:
Skip Montanarocafc8112004-04-07 15:46:05 +0000236 counts, calledfuncs, callers = \
237 pickle.load(open(self.infile, 'rb'))
238 self.update(self.__class__(counts, calledfuncs, callers))
Guido van Rossumb940e112007-01-10 16:19:56 +0000239 except (IOError, EOFError, ValueError) as err:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000240 print(("Skipping counts file %r: %s"
241 % (self.infile, err)), file=sys.stderr)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000242
Georg Brandl33c28812009-04-01 23:07:29 +0000243 def is_ignored_filename(self, filename):
244 """Return True if the filename does not refer to a file
245 we want to have reported.
246 """
247 return (filename == "<string>" or
248 filename.startswith("<doctest "))
249
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000250 def update(self, other):
251 """Merge in the data from another CoverageResults"""
252 counts = self.counts
253 calledfuncs = self.calledfuncs
Skip Montanarocafc8112004-04-07 15:46:05 +0000254 callers = self.callers
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000255 other_counts = other.counts
256 other_calledfuncs = other.calledfuncs
Skip Montanarocafc8112004-04-07 15:46:05 +0000257 other_callers = other.callers
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000258
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000259 for key in other_counts:
Jeremy Hylton38732e12003-04-21 22:04:46 +0000260 counts[key] = counts.get(key, 0) + other_counts[key]
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000261
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000262 for key in other_calledfuncs:
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000263 calledfuncs[key] = 1
264
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000265 for key in other_callers:
Skip Montanarocafc8112004-04-07 15:46:05 +0000266 callers[key] = 1
267
Jeremy Hylton38732e12003-04-21 22:04:46 +0000268 def write_results(self, show_missing=True, summary=False, coverdir=None):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000269 """
270 @param coverdir
271 """
Skip Montanarocafc8112004-04-07 15:46:05 +0000272 if self.calledfuncs:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000273 print()
274 print("functions called:")
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000275 calls = self.calledfuncs
Alexander Belopolsky533a1672010-07-20 19:55:18 +0000276 for filename, modulename, funcname in sorted(calls):
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000277 print(("filename: %s, modulename: %s, funcname: %s"
278 % (filename, modulename, funcname)))
Skip Montanarocafc8112004-04-07 15:46:05 +0000279
280 if self.callers:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000281 print()
282 print("calling relationships:")
Skip Montanarocafc8112004-04-07 15:46:05 +0000283 lastfile = lastcfile = ""
Georg Brandl33c28812009-04-01 23:07:29 +0000284 for ((pfile, pmod, pfunc), (cfile, cmod, cfunc)) \
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000285 in sorted(self.callers):
Skip Montanarocafc8112004-04-07 15:46:05 +0000286 if pfile != lastfile:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000287 print()
288 print("***", pfile, "***")
Skip Montanarocafc8112004-04-07 15:46:05 +0000289 lastfile = pfile
290 lastcfile = ""
291 if cfile != pfile and lastcfile != cfile:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000292 print(" -->", cfile)
Skip Montanarocafc8112004-04-07 15:46:05 +0000293 lastcfile = cfile
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000294 print(" %s.%s -> %s.%s" % (pmod, pfunc, cmod, cfunc))
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000295
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000296 # turn the counts data ("(filename, lineno) = count") into something
297 # accessible on a per-file basis
298 per_file = {}
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000299 for filename, lineno in self.counts:
Jeremy Hylton38732e12003-04-21 22:04:46 +0000300 lines_hit = per_file[filename] = per_file.get(filename, {})
301 lines_hit[lineno] = self.counts[(filename, lineno)]
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000302
303 # accumulate summary info, if needed
304 sums = {}
305
Guido van Rossumcc2b0162007-02-11 06:12:03 +0000306 for filename, count in per_file.items():
Georg Brandl33c28812009-04-01 23:07:29 +0000307 if self.is_ignored_filename(filename):
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000308 continue
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000309
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000310 if filename.endswith((".pyc", ".pyo")):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000311 filename = filename[:-1]
312
Jeremy Hylton38732e12003-04-21 22:04:46 +0000313 if coverdir is None:
314 dir = os.path.dirname(os.path.abspath(filename))
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000315 modulename = _modname(filename)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000316 else:
Jeremy Hylton38732e12003-04-21 22:04:46 +0000317 dir = coverdir
318 if not os.path.exists(dir):
319 os.makedirs(dir)
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000320 modulename = _fullmodname(filename)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000321
322 # If desired, get a list of the line numbers which represent
323 # executable content (returned as a dict for better lookup speed)
324 if show_missing:
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000325 lnotab = _find_executable_linenos(filename)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000326 else:
Jeremy Hylton38732e12003-04-21 22:04:46 +0000327 lnotab = {}
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000328
Jeremy Hylton38732e12003-04-21 22:04:46 +0000329 source = linecache.getlines(filename)
330 coverpath = os.path.join(dir, modulename + ".cover")
Victor Stinner64bc3b22010-11-07 15:47:36 +0000331 with open(filename, 'rb') as fp:
332 encoding, _ = tokenize.detect_encoding(fp.readline)
Jeremy Hylton38732e12003-04-21 22:04:46 +0000333 n_hits, n_lines = self.write_results_file(coverpath, source,
Victor Stinner64bc3b22010-11-07 15:47:36 +0000334 lnotab, count, encoding)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000335 if summary and n_lines:
336 percent = int(100 * n_hits / n_lines)
337 sums[modulename] = n_lines, percent, modulename, filename
338
339 if summary and sums:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000340 print("lines cov% module (path)")
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000341 for m in sorted(sums):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000342 n_lines, percent, modulename, filename = sums[m]
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000343 print("%5d %3d%% %s (%s)" % sums[m])
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000344
345 if self.outfile:
346 # try and store counts and module info into self.outfile
347 try:
Skip Montanarocafc8112004-04-07 15:46:05 +0000348 pickle.dump((self.counts, self.calledfuncs, self.callers),
Jeremy Hyltond0e27052003-10-14 20:12:06 +0000349 open(self.outfile, 'wb'), 1)
Guido van Rossumb940e112007-01-10 16:19:56 +0000350 except IOError as err:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000351 print("Can't save counts files because %s" % err, file=sys.stderr)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000352
Victor Stinner64bc3b22010-11-07 15:47:36 +0000353 def write_results_file(self, path, lines, lnotab, lines_hit, encoding=None):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000354 """Return a coverage results file in path."""
355
356 try:
Victor Stinner64bc3b22010-11-07 15:47:36 +0000357 outfile = open(path, "w", encoding=encoding)
Guido van Rossumb940e112007-01-10 16:19:56 +0000358 except IOError as err:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000359 print(("trace: Could not open %r for writing: %s"
360 "- skipping" % (path, err)), file=sys.stderr)
Guido van Rossumbbca8da2004-02-19 19:16:50 +0000361 return 0, 0
Jeremy Hylton38732e12003-04-21 22:04:46 +0000362
363 n_lines = 0
364 n_hits = 0
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000365 for lineno, line in enumerate(lines, 1):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000366 # do the blank/comment match to try to mark more lines
367 # (help the reader find stuff that hasn't been covered)
368 if lineno in lines_hit:
369 outfile.write("%5d: " % lines_hit[lineno])
370 n_hits += 1
371 n_lines += 1
372 elif rx_blank.match(line):
Walter Dörwaldc1711722003-07-15 10:34:02 +0000373 outfile.write(" ")
Jeremy Hylton38732e12003-04-21 22:04:46 +0000374 else:
375 # lines preceded by no marks weren't hit
376 # Highlight them if so indicated, unless the line contains
377 # #pragma: NO COVER
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000378 if lineno in lnotab and not PRAGMA_NOCOVER in line:
Jeremy Hylton38732e12003-04-21 22:04:46 +0000379 outfile.write(">>>>>> ")
Jeremy Hylton546e34b2003-06-26 14:56:17 +0000380 n_lines += 1
Jeremy Hylton38732e12003-04-21 22:04:46 +0000381 else:
382 outfile.write(" ")
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000383 outfile.write(line.expandtabs(8))
Jeremy Hylton38732e12003-04-21 22:04:46 +0000384 outfile.close()
385
386 return n_hits, n_lines
387
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000388def _find_lines_from_code(code, strs):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000389 """Return dict where keys are lines in the line number table."""
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000390 linenos = {}
391
Alexander Belopolskyff09ce22010-09-24 18:03:12 +0000392 for _, lineno in dis.findlinestarts(code):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000393 if lineno not in strs:
394 linenos[lineno] = 1
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000395
396 return linenos
397
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000398def _find_lines(code, strs):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000399 """Return lineno dict for all code objects reachable from code."""
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000400 # get all of the lineno information from the code of this scope level
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000401 linenos = _find_lines_from_code(code, strs)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000402
403 # and check the constants for references to other code objects
404 for c in code.co_consts:
Alexander Belopolsky4d770172010-09-13 18:14:34 +0000405 if inspect.iscode(c):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000406 # find another code object, so recurse into it
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000407 linenos.update(_find_lines(c, strs))
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000408 return linenos
409
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000410def _find_strings(filename, encoding=None):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000411 """Return a dict of possible docstring positions.
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000412
Jeremy Hylton38732e12003-04-21 22:04:46 +0000413 The dict maps line numbers to strings. There is an entry for
414 line that contains only a string or a part of a triple-quoted
415 string.
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000416 """
Jeremy Hylton38732e12003-04-21 22:04:46 +0000417 d = {}
418 # If the first token is a string, then it's the module docstring.
419 # Add this special case so that the test in the loop passes.
420 prev_ttype = token.INDENT
Benjamin Petersonb2fda232010-10-30 23:51:34 +0000421 with open(filename, encoding=encoding) as f:
422 tok = tokenize.generate_tokens(f.readline)
423 for ttype, tstr, start, end, line in tok:
424 if ttype == token.STRING:
425 if prev_ttype == token.INDENT:
426 sline, scol = start
427 eline, ecol = end
428 for i in range(sline, eline + 1):
429 d[i] = 1
430 prev_ttype = ttype
Jeremy Hylton38732e12003-04-21 22:04:46 +0000431 return d
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000432
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000433def _find_executable_linenos(filename):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000434 """Return dict where keys are line numbers in the line number table."""
Jeremy Hylton38732e12003-04-21 22:04:46 +0000435 try:
Victor Stinner58c07522010-11-09 01:08:59 +0000436 with tokenize.open(filename) as f:
Benjamin Petersonb2fda232010-10-30 23:51:34 +0000437 prog = f.read()
Victor Stinner58c07522010-11-09 01:08:59 +0000438 encoding = f.encoding
Guido van Rossumb940e112007-01-10 16:19:56 +0000439 except IOError as err:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000440 print(("Not printing coverage data for %r: %s"
441 % (filename, err)), file=sys.stderr)
Jeremy Hylton38732e12003-04-21 22:04:46 +0000442 return {}
443 code = compile(prog, filename, "exec")
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000444 strs = _find_strings(filename, encoding)
445 return _find_lines(code, strs)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000446
447class Trace:
Skip Montanarocafc8112004-04-07 15:46:05 +0000448 def __init__(self, count=1, trace=1, countfuncs=0, countcallers=0,
Christian Heimes380f7f22008-02-28 11:19:05 +0000449 ignoremods=(), ignoredirs=(), infile=None, outfile=None,
450 timing=False):
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000451 """
452 @param count true iff it should count number of times each
Tim Petersf2715e02003-02-19 02:35:07 +0000453 line is executed
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000454 @param trace true iff it should print out each line that is
Tim Petersf2715e02003-02-19 02:35:07 +0000455 being counted
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000456 @param countfuncs true iff it should just output a list of
457 (filename, modulename, funcname,) for functions
458 that were called at least once; This overrides
Tim Petersf2715e02003-02-19 02:35:07 +0000459 `count' and `trace'
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000460 @param ignoremods a list of the names of modules to ignore
461 @param ignoredirs a list of the names of directories to ignore
Tim Petersf2715e02003-02-19 02:35:07 +0000462 all of the (recursive) contents of
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000463 @param infile file from which to read stored counts to be
Tim Petersf2715e02003-02-19 02:35:07 +0000464 added into the results
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000465 @param outfile file in which to write the results
Christian Heimes380f7f22008-02-28 11:19:05 +0000466 @param timing true iff timing information be displayed
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000467 """
468 self.infile = infile
469 self.outfile = outfile
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000470 self.ignore = _Ignore(ignoremods, ignoredirs)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000471 self.counts = {} # keys are (filename, linenumber)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000472 self.pathtobasename = {} # for memoizing os.path.basename
473 self.donothing = 0
474 self.trace = trace
475 self._calledfuncs = {}
Skip Montanarocafc8112004-04-07 15:46:05 +0000476 self._callers = {}
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000477 self._caller_cache = {}
Christian Heimes380f7f22008-02-28 11:19:05 +0000478 self.start_time = None
479 if timing:
480 self.start_time = time.time()
Skip Montanarocafc8112004-04-07 15:46:05 +0000481 if countcallers:
482 self.globaltrace = self.globaltrace_trackcallers
483 elif countfuncs:
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000484 self.globaltrace = self.globaltrace_countfuncs
485 elif trace and count:
486 self.globaltrace = self.globaltrace_lt
487 self.localtrace = self.localtrace_trace_and_count
488 elif trace:
489 self.globaltrace = self.globaltrace_lt
490 self.localtrace = self.localtrace_trace
491 elif count:
492 self.globaltrace = self.globaltrace_lt
493 self.localtrace = self.localtrace_count
494 else:
495 # Ahem -- do nothing? Okay.
496 self.donothing = 1
497
498 def run(self, cmd):
499 import __main__
500 dict = __main__.__dict__
Alexander Belopolsky0ae33612010-09-27 15:49:20 +0000501 self.runctx(cmd, dict, dict)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000502
503 def runctx(self, cmd, globals=None, locals=None):
504 if globals is None: globals = {}
505 if locals is None: locals = {}
506 if not self.donothing:
Alexander Belopolsky25b57412010-11-06 01:31:16 +0000507 _settrace(self.globaltrace)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000508 try:
Georg Brandl7cae87c2006-09-06 06:51:57 +0000509 exec(cmd, globals, locals)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000510 finally:
511 if not self.donothing:
Alexander Belopolsky25b57412010-11-06 01:31:16 +0000512 _unsettrace()
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000513
514 def runfunc(self, func, *args, **kw):
515 result = None
516 if not self.donothing:
517 sys.settrace(self.globaltrace)
518 try:
Guido van Rossum68468eb2003-02-27 20:14:51 +0000519 result = func(*args, **kw)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000520 finally:
521 if not self.donothing:
522 sys.settrace(None)
523 return result
524
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000525 def file_module_function_of(self, frame):
526 code = frame.f_code
527 filename = code.co_filename
528 if filename:
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000529 modulename = _modname(filename)
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000530 else:
531 modulename = None
532
533 funcname = code.co_name
534 clsname = None
535 if code in self._caller_cache:
536 if self._caller_cache[code] is not None:
537 clsname = self._caller_cache[code]
538 else:
539 self._caller_cache[code] = None
540 ## use of gc.get_referrers() was suggested by Michael Hudson
541 # all functions which refer to this code object
542 funcs = [f for f in gc.get_referrers(code)
Alexander Belopolsky4d770172010-09-13 18:14:34 +0000543 if inspect.isfunction(f)]
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000544 # require len(func) == 1 to avoid ambiguity caused by calls to
545 # new.function(): "In the face of ambiguity, refuse the
546 # temptation to guess."
547 if len(funcs) == 1:
548 dicts = [d for d in gc.get_referrers(funcs[0])
549 if isinstance(d, dict)]
550 if len(dicts) == 1:
551 classes = [c for c in gc.get_referrers(dicts[0])
552 if hasattr(c, "__bases__")]
553 if len(classes) == 1:
554 # ditto for new.classobj()
Alexander Belopolsky4d770172010-09-13 18:14:34 +0000555 clsname = classes[0].__name__
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000556 # cache the result - assumption is that new.* is
557 # not called later to disturb this relationship
558 # _caller_cache could be flushed if functions in
559 # the new module get called.
560 self._caller_cache[code] = clsname
561 if clsname is not None:
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000562 funcname = "%s.%s" % (clsname, funcname)
563
564 return filename, modulename, funcname
565
Skip Montanarocafc8112004-04-07 15:46:05 +0000566 def globaltrace_trackcallers(self, frame, why, arg):
567 """Handler for call events.
568
569 Adds information about who called who to the self._callers dict.
570 """
571 if why == 'call':
572 # XXX Should do a better job of identifying methods
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000573 this_func = self.file_module_function_of(frame)
574 parent_func = self.file_module_function_of(frame.f_back)
Skip Montanarocafc8112004-04-07 15:46:05 +0000575 self._callers[(parent_func, this_func)] = 1
576
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000577 def globaltrace_countfuncs(self, frame, why, arg):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000578 """Handler for call events.
Tim Peters0eadaac2003-04-24 16:02:54 +0000579
Jeremy Hylton38732e12003-04-21 22:04:46 +0000580 Adds (filename, modulename, funcname) to the self._calledfuncs dict.
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000581 """
582 if why == 'call':
Skip Montanaro5bfd9842004-04-10 16:29:58 +0000583 this_func = self.file_module_function_of(frame)
584 self._calledfuncs[this_func] = 1
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000585
586 def globaltrace_lt(self, frame, why, arg):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000587 """Handler for call events.
588
589 If the code block being entered is to be ignored, returns `None',
590 else returns self.localtrace.
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000591 """
592 if why == 'call':
Jeremy Hylton38732e12003-04-21 22:04:46 +0000593 code = frame.f_code
Thomas Wouterscf297e42007-02-23 15:07:44 +0000594 filename = frame.f_globals.get('__file__', None)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000595 if filename:
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000596 # XXX _modname() doesn't work right for packages, so
Jeremy Hyltondfbfe732003-04-21 22:49:17 +0000597 # the ignore support won't work right for packages
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000598 modulename = _modname(filename)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000599 if modulename is not None:
600 ignore_it = self.ignore.names(filename, modulename)
601 if not ignore_it:
602 if self.trace:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000603 print((" --- modulename: %s, funcname: %s"
604 % (modulename, code.co_name)))
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000605 return self.localtrace
606 else:
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000607 return None
608
609 def localtrace_trace_and_count(self, frame, why, arg):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000610 if why == "line":
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000611 # record the file name and line number of every trace
Jeremy Hylton38732e12003-04-21 22:04:46 +0000612 filename = frame.f_code.co_filename
613 lineno = frame.f_lineno
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000614 key = filename, lineno
615 self.counts[key] = self.counts.get(key, 0) + 1
Tim Petersf2715e02003-02-19 02:35:07 +0000616
Christian Heimes380f7f22008-02-28 11:19:05 +0000617 if self.start_time:
618 print('%.2f' % (time.time() - self.start_time), end=' ')
Jeremy Hylton38732e12003-04-21 22:04:46 +0000619 bname = os.path.basename(filename)
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000620 print("%s(%d): %s" % (bname, lineno,
Georg Brandldc50c692010-08-02 12:40:22 +0000621 linecache.getline(filename, lineno)), end='')
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000622 return self.localtrace
623
624 def localtrace_trace(self, frame, why, arg):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000625 if why == "line":
626 # record the file name and line number of every trace
627 filename = frame.f_code.co_filename
628 lineno = frame.f_lineno
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000629
Christian Heimes380f7f22008-02-28 11:19:05 +0000630 if self.start_time:
631 print('%.2f' % (time.time() - self.start_time), end=' ')
Jeremy Hylton38732e12003-04-21 22:04:46 +0000632 bname = os.path.basename(filename)
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000633 print("%s(%d): %s" % (bname, lineno,
Georg Brandldc50c692010-08-02 12:40:22 +0000634 linecache.getline(filename, lineno)), end='')
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000635 return self.localtrace
636
637 def localtrace_count(self, frame, why, arg):
Jeremy Hylton38732e12003-04-21 22:04:46 +0000638 if why == "line":
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000639 filename = frame.f_code.co_filename
640 lineno = frame.f_lineno
641 key = filename, lineno
642 self.counts[key] = self.counts.get(key, 0) + 1
643 return self.localtrace
644
645 def results(self):
646 return CoverageResults(self.counts, infile=self.infile,
647 outfile=self.outfile,
Skip Montanarocafc8112004-04-07 15:46:05 +0000648 calledfuncs=self._calledfuncs,
649 callers=self._callers)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000650
651def _err_exit(msg):
652 sys.stderr.write("%s: %s\n" % (sys.argv[0], msg))
653 sys.exit(1)
654
655def main(argv=None):
656 import getopt
657
658 if argv is None:
659 argv = sys.argv
660 try:
Christian Heimes380f7f22008-02-28 11:19:05 +0000661 opts, prog_argv = getopt.getopt(argv[1:], "tcrRf:d:msC:lTg",
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000662 ["help", "version", "trace", "count",
663 "report", "no-report", "summary",
664 "file=", "missing",
665 "ignore-module=", "ignore-dir=",
Skip Montanarocafc8112004-04-07 15:46:05 +0000666 "coverdir=", "listfuncs",
Christian Heimes380f7f22008-02-28 11:19:05 +0000667 "trackcalls", "timing"])
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000668
Guido van Rossumb940e112007-01-10 16:19:56 +0000669 except getopt.error as msg:
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000670 sys.stderr.write("%s: %s\n" % (sys.argv[0], msg))
671 sys.stderr.write("Try `%s --help' for more information\n"
672 % sys.argv[0])
673 sys.exit(1)
674
675 trace = 0
676 count = 0
677 report = 0
678 no_report = 0
679 counts_file = None
680 missing = 0
681 ignore_modules = []
682 ignore_dirs = []
683 coverdir = None
684 summary = 0
685 listfuncs = False
Skip Montanarocafc8112004-04-07 15:46:05 +0000686 countcallers = False
Christian Heimes380f7f22008-02-28 11:19:05 +0000687 timing = False
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000688
689 for opt, val in opts:
690 if opt == "--help":
691 usage(sys.stdout)
692 sys.exit(0)
693
694 if opt == "--version":
695 sys.stdout.write("trace 2.0\n")
696 sys.exit(0)
697
Skip Montanarocafc8112004-04-07 15:46:05 +0000698 if opt == "-T" or opt == "--trackcalls":
699 countcallers = True
700 continue
701
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000702 if opt == "-l" or opt == "--listfuncs":
703 listfuncs = True
704 continue
705
Christian Heimes380f7f22008-02-28 11:19:05 +0000706 if opt == "-g" or opt == "--timing":
707 timing = True
708 continue
709
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000710 if opt == "-t" or opt == "--trace":
711 trace = 1
712 continue
713
714 if opt == "-c" or opt == "--count":
715 count = 1
716 continue
717
718 if opt == "-r" or opt == "--report":
719 report = 1
720 continue
721
722 if opt == "-R" or opt == "--no-report":
723 no_report = 1
724 continue
725
726 if opt == "-f" or opt == "--file":
727 counts_file = val
728 continue
729
730 if opt == "-m" or opt == "--missing":
731 missing = 1
732 continue
733
734 if opt == "-C" or opt == "--coverdir":
735 coverdir = val
736 continue
737
738 if opt == "-s" or opt == "--summary":
739 summary = 1
740 continue
741
742 if opt == "--ignore-module":
Georg Brandlfceab5a2008-01-19 20:08:23 +0000743 for mod in val.split(","):
744 ignore_modules.append(mod.strip())
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000745 continue
746
747 if opt == "--ignore-dir":
748 for s in val.split(os.pathsep):
749 s = os.path.expandvars(s)
750 # should I also call expanduser? (after all, could use $HOME)
751
752 s = s.replace("$prefix",
753 os.path.join(sys.prefix, "lib",
754 "python" + sys.version[:3]))
755 s = s.replace("$exec_prefix",
756 os.path.join(sys.exec_prefix, "lib",
757 "python" + sys.version[:3]))
758 s = os.path.normpath(s)
759 ignore_dirs.append(s)
760 continue
761
762 assert 0, "Should never get here"
763
764 if listfuncs and (count or trace):
765 _err_exit("cannot specify both --listfuncs and (--trace or --count)")
766
Skip Montanarocafc8112004-04-07 15:46:05 +0000767 if not (count or trace or report or listfuncs or countcallers):
768 _err_exit("must specify one of --trace, --count, --report, "
769 "--listfuncs, or --trackcalls")
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000770
771 if report and no_report:
772 _err_exit("cannot specify both --report and --no-report")
773
774 if report and not counts_file:
775 _err_exit("--report requires a --file")
776
777 if no_report and len(prog_argv) == 0:
778 _err_exit("missing name of file to run")
779
780 # everything is ready
781 if report:
782 results = CoverageResults(infile=counts_file, outfile=counts_file)
783 results.write_results(missing, summary=summary, coverdir=coverdir)
784 else:
785 sys.argv = prog_argv
786 progname = prog_argv[0]
787 sys.path[0] = os.path.split(progname)[0]
788
789 t = Trace(count, trace, countfuncs=listfuncs,
Skip Montanarocafc8112004-04-07 15:46:05 +0000790 countcallers=countcallers, ignoremods=ignore_modules,
791 ignoredirs=ignore_dirs, infile=counts_file,
Christian Heimes380f7f22008-02-28 11:19:05 +0000792 outfile=counts_file, timing=timing)
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000793 try:
Alexander Belopolsky3f8ecab2010-07-21 17:43:42 +0000794 with open(progname) as fp:
795 code = compile(fp.read(), progname, 'exec')
Georg Brandl8f9f4662010-08-01 08:35:29 +0000796 # try to emulate __main__ namespace as much as possible
797 globs = {
798 '__file__': progname,
799 '__name__': '__main__',
800 '__package__': None,
801 '__cached__': None,
802 }
803 t.runctx(code, globs, globs)
Guido van Rossumb940e112007-01-10 16:19:56 +0000804 except IOError as err:
Jeremy Hylton38732e12003-04-21 22:04:46 +0000805 _err_exit("Cannot run file %r because: %s" % (sys.argv[0], err))
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000806 except SystemExit:
807 pass
808
809 results = t.results()
810
811 if not no_report:
812 results.write_results(missing, summary=summary, coverdir=coverdir)
813
Alexander Belopolsky44454af2010-11-20 18:21:07 +0000814# Deprecated API
815def usage(outfile):
816 _warn("The trace.usage() function is deprecated",
817 DeprecationWarning, 2)
818 _usage(outfile)
819
820class Ignore(_Ignore):
821 def __init__(self, modules=None, dirs=None):
822 _warn("The class trace.Ignore is deprecated",
823 DeprecationWarning, 2)
824 _Ignore.__init__(self, modules, dirs)
825
826def modname(path):
827 _warn("The trace.modname() function is deprecated",
828 DeprecationWarning, 2)
829 return _modname(path)
830
831def fullmodname(path):
832 _warn("The trace.fullmodname() function is deprecated",
833 DeprecationWarning, 2)
834 return _fullmodname(path)
835
836def find_lines_from_code(code, strs):
837 _warn("The trace.find_lines_from_code() function is deprecated",
838 DeprecationWarning, 2)
839 return _find_lines_from_code(code, strs)
840
841def find_lines(code, strs):
842 _warn("The trace.find_lines() function is deprecated",
843 DeprecationWarning, 2)
844 return _find_lines(code, strs)
845
846def find_strings(filename, encoding=None):
847 _warn("The trace.find_strings() function is deprecated",
848 DeprecationWarning, 2)
849 return _find_strings(filename, encoding=None)
850
851def find_executable_linenos(filename):
852 _warn("The trace.find_executable_linenos() function is deprecated",
853 DeprecationWarning, 2)
854 return _find_executable_linenos(filename)
855
Jeremy Hylton4edaa0d2003-02-18 15:06:17 +0000856if __name__=='__main__':
857 main()