blob: 33b86c7e6e5042d5cb3e51ef5000a6e66c4eaf6a [file] [log] [blame]
Guido van Rossume7b146f2000-02-04 15:28:42 +00001"""Extract, format and print information about Python stack traces."""
Guido van Rossum526beed1994-07-01 15:36:46 +00002
3import linecache
Guido van Rossum526beed1994-07-01 15:36:46 +00004import sys
5
Skip Montanaro40fc1602001-03-01 04:27:19 +00006__all__ = ['extract_stack', 'extract_tb', 'format_exception',
7 'format_exception_only', 'format_list', 'format_stack',
Neil Schemenauerf607fc52003-11-05 23:03:00 +00008 'format_tb', 'print_exc', 'format_exc', 'print_exception',
Georg Brandlc7372832008-05-12 18:03:53 +00009 'print_last', 'print_stack', 'print_tb']
Skip Montanaro40fc1602001-03-01 04:27:19 +000010
Guido van Rossum194e20a1995-09-20 20:31:51 +000011def _print(file, str='', terminator='\n'):
Tim Petersb90f89a2001-01-15 03:26:36 +000012 file.write(str+terminator)
Guido van Rossumdcc057a1996-08-12 23:18:13 +000013
14
15def print_list(extracted_list, file=None):
Tim Petersb90f89a2001-01-15 03:26:36 +000016 """Print the list of tuples as returned by extract_tb() or
17 extract_stack() as a formatted stack trace to the given file."""
Raymond Hettinger10ff7062002-06-02 03:04:52 +000018 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +000019 file = sys.stderr
20 for filename, lineno, name, line in extracted_list:
21 _print(file,
22 ' File "%s", line %d, in %s' % (filename,lineno,name))
23 if line:
Eric S. Raymondec3bbde2001-02-09 09:39:08 +000024 _print(file, ' %s' % line.strip())
Guido van Rossumdcc057a1996-08-12 23:18:13 +000025
26def format_list(extracted_list):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000027 """Format a list of traceback entry tuples for printing.
28
29 Given a list of tuples as returned by extract_tb() or
Tim Petersb90f89a2001-01-15 03:26:36 +000030 extract_stack(), return a list of strings ready for printing.
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000031 Each string in the resulting list corresponds to the item with the
32 same index in the argument list. Each string ends in a newline;
33 the strings may contain internal newlines as well, for those items
34 whose source text line is not None.
35 """
Tim Petersb90f89a2001-01-15 03:26:36 +000036 list = []
37 for filename, lineno, name, line in extracted_list:
38 item = ' File "%s", line %d, in %s\n' % (filename,lineno,name)
39 if line:
Eric S. Raymondec3bbde2001-02-09 09:39:08 +000040 item = item + ' %s\n' % line.strip()
Tim Petersb90f89a2001-01-15 03:26:36 +000041 list.append(item)
42 return list
43
Guido van Rossum194e20a1995-09-20 20:31:51 +000044
45def print_tb(tb, limit=None, file=None):
Tim Petersb90f89a2001-01-15 03:26:36 +000046 """Print up to 'limit' stack trace entries from the traceback 'tb'.
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000047
48 If 'limit' is omitted or None, all entries are printed. If 'file'
49 is omitted or None, the output goes to sys.stderr; otherwise
50 'file' should be an open file or file-like object with a write()
51 method.
52 """
Raymond Hettinger10ff7062002-06-02 03:04:52 +000053 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +000054 file = sys.stderr
55 if limit is None:
56 if hasattr(sys, 'tracebacklimit'):
57 limit = sys.tracebacklimit
58 n = 0
59 while tb is not None and (limit is None or n < limit):
60 f = tb.tb_frame
Michael W. Hudsondd32a912002-08-15 14:59:02 +000061 lineno = tb.tb_lineno
Tim Petersb90f89a2001-01-15 03:26:36 +000062 co = f.f_code
63 filename = co.co_filename
64 name = co.co_name
65 _print(file,
Georg Brandl236f7972009-04-05 14:28:42 +000066 ' File "%s", line %d, in %s' % (filename, lineno, name))
Hye-Shik Chang182ac852004-10-26 09:16:42 +000067 linecache.checkcache(filename)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +000068 line = linecache.getline(filename, lineno, f.f_globals)
Eric S. Raymondec3bbde2001-02-09 09:39:08 +000069 if line: _print(file, ' ' + line.strip())
Tim Petersb90f89a2001-01-15 03:26:36 +000070 tb = tb.tb_next
71 n = n+1
Guido van Rossum526beed1994-07-01 15:36:46 +000072
Georg Brandl2ad07c32009-09-16 14:24:29 +000073def format_tb(tb, limit=None):
Tim Petersb90f89a2001-01-15 03:26:36 +000074 """A shorthand for 'format_list(extract_stack(f, limit))."""
75 return format_list(extract_tb(tb, limit))
Guido van Rossum28e99fe1995-08-04 04:30:30 +000076
Georg Brandl2ad07c32009-09-16 14:24:29 +000077def extract_tb(tb, limit=None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000078 """Return list of up to limit pre-processed entries from traceback.
79
80 This is useful for alternate formatting of stack traces. If
81 'limit' is omitted or None, all entries are extracted. A
82 pre-processed stack trace entry is a quadruple (filename, line
83 number, function name, text) representing the information that is
84 usually printed for a stack trace. The text is a string with
85 leading and trailing whitespace stripped; if the source is not
86 available it is None.
87 """
Tim Petersb90f89a2001-01-15 03:26:36 +000088 if limit is None:
89 if hasattr(sys, 'tracebacklimit'):
90 limit = sys.tracebacklimit
91 list = []
92 n = 0
93 while tb is not None and (limit is None or n < limit):
94 f = tb.tb_frame
Michael W. Hudsondd32a912002-08-15 14:59:02 +000095 lineno = tb.tb_lineno
Tim Petersb90f89a2001-01-15 03:26:36 +000096 co = f.f_code
97 filename = co.co_filename
98 name = co.co_name
Hye-Shik Chang182ac852004-10-26 09:16:42 +000099 linecache.checkcache(filename)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000100 line = linecache.getline(filename, lineno, f.f_globals)
Eric S. Raymondec3bbde2001-02-09 09:39:08 +0000101 if line: line = line.strip()
Tim Petersb90f89a2001-01-15 03:26:36 +0000102 else: line = None
103 list.append((filename, lineno, name, line))
104 tb = tb.tb_next
105 n = n+1
106 return list
Guido van Rossum526beed1994-07-01 15:36:46 +0000107
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000108
Benjamin Petersone6528212008-07-15 15:32:09 +0000109_cause_message = (
110 "\nThe above exception was the direct cause "
111 "of the following exception:\n")
112
113_context_message = (
114 "\nDuring handling of the above exception, "
115 "another exception occurred:\n")
116
117def _iter_chain(exc, custom_tb=None, seen=None):
118 if seen is None:
119 seen = set()
120 seen.add(exc)
121 its = []
Benjamin Petersond5a1c442012-05-14 22:09:31 -0700122 context = exc.__context__
Benjamin Petersone6528212008-07-15 15:32:09 +0000123 cause = exc.__cause__
Benjamin Petersond5a1c442012-05-14 22:09:31 -0700124 if cause is not None and cause not in seen:
Nick Coghlanab7bf212012-02-26 17:49:52 +1000125 its.append(_iter_chain(cause, False, seen))
126 its.append([(_cause_message, None)])
Benjamin Petersond5a1c442012-05-14 22:09:31 -0700127 elif (context is not None and
128 not exc.__suppress_context__ and
129 context not in seen):
130 its.append(_iter_chain(context, None, seen))
131 its.append([(_context_message, None)])
Benjamin Petersone6528212008-07-15 15:32:09 +0000132 its.append([(exc, custom_tb or exc.__traceback__)])
Hirokazu Yamamoto54a1cc62008-09-09 17:55:11 +0000133 # itertools.chain is in an extension module and may be unavailable
134 for it in its:
Philip Jenvey4993cc02012-10-01 12:53:43 -0700135 yield from it
Benjamin Petersone6528212008-07-15 15:32:09 +0000136
137
138def print_exception(etype, value, tb, limit=None, file=None, chain=True):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000139 """Print exception up to 'limit' stack trace entries from 'tb' to 'file'.
140
141 This differs from print_tb() in the following ways: (1) if
142 traceback is not None, it prints a header "Traceback (most recent
143 call last):"; (2) it prints the exception type and value after the
144 stack trace; (3) if type is SyntaxError and value has the
145 appropriate format, it prints the line where the syntax error
Tim Petersb90f89a2001-01-15 03:26:36 +0000146 occurred with a caret on the next line indicating the approximate
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000147 position of the error.
148 """
Raymond Hettinger10ff7062002-06-02 03:04:52 +0000149 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +0000150 file = sys.stderr
Benjamin Petersone6528212008-07-15 15:32:09 +0000151 if chain:
152 values = _iter_chain(value, tb)
153 else:
154 values = [(value, tb)]
155 for value, tb in values:
156 if isinstance(value, str):
157 _print(file, value)
158 continue
159 if tb:
160 _print(file, 'Traceback (most recent call last):')
161 print_tb(tb, limit, file)
162 lines = format_exception_only(type(value), value)
Georg Brandl236f7972009-04-05 14:28:42 +0000163 for line in lines:
164 _print(file, line, '')
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000165
Benjamin Petersone6528212008-07-15 15:32:09 +0000166def format_exception(etype, value, tb, limit=None, chain=True):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000167 """Format a stack trace and the exception information.
168
169 The arguments have the same meaning as the corresponding arguments
170 to print_exception(). The return value is a list of strings, each
Tim Petersb90f89a2001-01-15 03:26:36 +0000171 ending in a newline and some containing internal newlines. When
172 these lines are concatenated and printed, exactly the same text is
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000173 printed as does print_exception().
174 """
Benjamin Petersone6528212008-07-15 15:32:09 +0000175 list = []
176 if chain:
177 values = _iter_chain(value, tb)
Tim Petersb90f89a2001-01-15 03:26:36 +0000178 else:
Benjamin Petersone6528212008-07-15 15:32:09 +0000179 values = [(value, tb)]
180 for value, tb in values:
181 if isinstance(value, str):
182 list.append(value + '\n')
183 continue
184 if tb:
185 list.append('Traceback (most recent call last):\n')
186 list.extend(format_tb(tb, limit))
187 list.extend(format_exception_only(type(value), value))
Tim Petersb90f89a2001-01-15 03:26:36 +0000188 return list
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000189
190def format_exception_only(etype, value):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000191 """Format the exception part of a traceback.
192
193 The arguments are the exception type and value such as given by
194 sys.last_type and sys.last_value. The return value is a list of
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000195 strings, each ending in a newline.
196
197 Normally, the list contains a single string; however, for
198 SyntaxError exceptions, it contains several lines that (when
199 printed) display detailed information about where the syntax
200 error occurred.
201
202 The message indicating which exception occurred is always the last
203 string in the list.
204
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000205 """
Thomas Wouters89f507f2006-12-13 04:49:30 +0000206 # Gracefully handle (the way Python 2.4 and earlier did) the case of
207 # being called with (None, None).
208 if etype is None:
209 return [_format_final_exc_line(etype, value)]
210
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000211 stype = etype.__name__
Guido van Rossum6a2a2a02006-08-26 20:37:44 +0000212 smod = etype.__module__
Georg Brandl1a3284e2007-12-02 09:40:06 +0000213 if smod not in ("__main__", "builtins"):
Guido van Rossum6a2a2a02006-08-26 20:37:44 +0000214 stype = smod + '.' + stype
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000215
216 if not issubclass(etype, SyntaxError):
217 return [_format_final_exc_line(stype, value)]
218
219 # It was a syntax error; show exactly where the problem was found.
220 lines = []
Guido van Rossum33d26892007-08-05 15:29:28 +0000221 filename = value.filename or "<string>"
222 lineno = str(value.lineno) or '?'
223 lines.append(' File "%s", line %s\n' % (filename, lineno))
224 badline = value.text
225 offset = value.offset
226 if badline is not None:
227 lines.append(' %s\n' % badline.strip())
228 if offset is not None:
Georg Brandl3cfdd9c2009-06-04 10:21:10 +0000229 caretspace = badline.rstrip('\n')[:offset].lstrip()
Guido van Rossum33d26892007-08-05 15:29:28 +0000230 # non-space whitespace (likes tabs) must be kept for alignment
231 caretspace = ((c.isspace() and c or ' ') for c in caretspace)
232 # only three spaces to account for offset1 == pos 0
233 lines.append(' %s^\n' % ''.join(caretspace))
234 msg = value.msg or "<no detail available>"
235 lines.append("%s: %s\n" % (stype, msg))
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000236 return lines
237
238def _format_final_exc_line(etype, value):
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000239 valuestr = _some_str(value)
240 if value is None or not valuestr:
241 line = "%s\n" % etype
Tim Petersb90f89a2001-01-15 03:26:36 +0000242 else:
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000243 line = "%s: %s\n" % (etype, valuestr)
244 return line
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000245
Guido van Rossum2823f032000-08-22 02:04:46 +0000246def _some_str(value):
Tim Petersb90f89a2001-01-15 03:26:36 +0000247 try:
248 return str(value)
249 except:
250 return '<unprintable %s object>' % type(value).__name__
Guido van Rossum2823f032000-08-22 02:04:46 +0000251
Guido van Rossum526beed1994-07-01 15:36:46 +0000252
Benjamin Petersone6528212008-07-15 15:32:09 +0000253def print_exc(limit=None, file=None, chain=True):
Neal Norwitzac3625f2006-03-17 05:49:33 +0000254 """Shorthand for 'print_exception(*sys.exc_info(), limit, file)'."""
Raymond Hettinger10ff7062002-06-02 03:04:52 +0000255 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +0000256 file = sys.stderr
257 try:
258 etype, value, tb = sys.exc_info()
Benjamin Petersone6528212008-07-15 15:32:09 +0000259 print_exception(etype, value, tb, limit, file, chain)
Tim Petersb90f89a2001-01-15 03:26:36 +0000260 finally:
261 etype = value = tb = None
Guido van Rossum526beed1994-07-01 15:36:46 +0000262
Neil Schemenauerf607fc52003-11-05 23:03:00 +0000263
Benjamin Petersone6528212008-07-15 15:32:09 +0000264def format_exc(limit=None, chain=True):
Neil Schemenauerf607fc52003-11-05 23:03:00 +0000265 """Like print_exc() but return a string."""
266 try:
267 etype, value, tb = sys.exc_info()
Benjamin Petersone6528212008-07-15 15:32:09 +0000268 return ''.join(
269 format_exception(etype, value, tb, limit, chain))
Neil Schemenauerf607fc52003-11-05 23:03:00 +0000270 finally:
271 etype = value = tb = None
Tim Peters58eb11c2004-01-18 20:29:55 +0000272
Neil Schemenauerf607fc52003-11-05 23:03:00 +0000273
Benjamin Petersone6528212008-07-15 15:32:09 +0000274def print_last(limit=None, file=None, chain=True):
Tim Petersb90f89a2001-01-15 03:26:36 +0000275 """This is a shorthand for 'print_exception(sys.last_type,
276 sys.last_value, sys.last_traceback, limit, file)'."""
Benjamin Petersone549ead2009-03-28 21:42:05 +0000277 if not hasattr(sys, "last_type"):
278 raise ValueError("no last exception")
Raymond Hettinger10ff7062002-06-02 03:04:52 +0000279 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +0000280 file = sys.stderr
281 print_exception(sys.last_type, sys.last_value, sys.last_traceback,
Benjamin Petersone6528212008-07-15 15:32:09 +0000282 limit, file, chain)
Guido van Rossumdcc057a1996-08-12 23:18:13 +0000283
284
285def print_stack(f=None, limit=None, file=None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000286 """Print a stack trace from its invocation point.
Tim Petersa19a1682001-03-29 04:36:09 +0000287
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000288 The optional 'f' argument can be used to specify an alternate
289 stack frame at which to start. The optional 'limit' and 'file'
290 arguments have the same meaning as for print_exception().
291 """
Tim Petersb90f89a2001-01-15 03:26:36 +0000292 if f is None:
293 try:
294 raise ZeroDivisionError
295 except ZeroDivisionError:
296 f = sys.exc_info()[2].tb_frame.f_back
297 print_list(extract_stack(f, limit), file)
Guido van Rossumdcc057a1996-08-12 23:18:13 +0000298
299def format_stack(f=None, limit=None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000300 """Shorthand for 'format_list(extract_stack(f, limit))'."""
Tim Petersb90f89a2001-01-15 03:26:36 +0000301 if f is None:
302 try:
303 raise ZeroDivisionError
304 except ZeroDivisionError:
305 f = sys.exc_info()[2].tb_frame.f_back
306 return format_list(extract_stack(f, limit))
Guido van Rossumdcc057a1996-08-12 23:18:13 +0000307
Georg Brandl2ad07c32009-09-16 14:24:29 +0000308def extract_stack(f=None, limit=None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000309 """Extract the raw traceback from the current stack frame.
310
311 The return value has the same format as for extract_tb(). The
312 optional 'f' and 'limit' arguments have the same meaning as for
313 print_stack(). Each item in the list is a quadruple (filename,
314 line number, function name, text), and the entries are in order
315 from oldest to newest stack frame.
316 """
Tim Petersb90f89a2001-01-15 03:26:36 +0000317 if f is None:
318 try:
319 raise ZeroDivisionError
320 except ZeroDivisionError:
321 f = sys.exc_info()[2].tb_frame.f_back
322 if limit is None:
323 if hasattr(sys, 'tracebacklimit'):
324 limit = sys.tracebacklimit
325 list = []
326 n = 0
327 while f is not None and (limit is None or n < limit):
Michael W. Hudsondd32a912002-08-15 14:59:02 +0000328 lineno = f.f_lineno
Tim Petersb90f89a2001-01-15 03:26:36 +0000329 co = f.f_code
330 filename = co.co_filename
331 name = co.co_name
Hye-Shik Chang182ac852004-10-26 09:16:42 +0000332 linecache.checkcache(filename)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000333 line = linecache.getline(filename, lineno, f.f_globals)
Eric S. Raymondec3bbde2001-02-09 09:39:08 +0000334 if line: line = line.strip()
Tim Petersb90f89a2001-01-15 03:26:36 +0000335 else: line = None
336 list.append((filename, lineno, name, line))
337 f = f.f_back
338 n = n+1
339 list.reverse()
340 return list