blob: 11ece25ca61f12fc9e1712d393379b92da365e2f [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
Guido van Rossumc7acf2a1995-02-27 13:15:45 +00005import types
Guido van Rossum526beed1994-07-01 15:36:46 +00006
Skip Montanaro40fc1602001-03-01 04:27:19 +00007__all__ = ['extract_stack', 'extract_tb', 'format_exception',
8 'format_exception_only', 'format_list', 'format_stack',
Neil Schemenauerf607fc52003-11-05 23:03:00 +00009 'format_tb', 'print_exc', 'format_exc', 'print_exception',
10 'print_last', 'print_stack', 'print_tb', 'tb_lineno']
Skip Montanaro40fc1602001-03-01 04:27:19 +000011
Guido van Rossum194e20a1995-09-20 20:31:51 +000012def _print(file, str='', terminator='\n'):
Tim Petersb90f89a2001-01-15 03:26:36 +000013 file.write(str+terminator)
Guido van Rossumdcc057a1996-08-12 23:18:13 +000014
15
16def print_list(extracted_list, file=None):
Tim Petersb90f89a2001-01-15 03:26:36 +000017 """Print the list of tuples as returned by extract_tb() or
18 extract_stack() as a formatted stack trace to the given file."""
Raymond Hettinger10ff7062002-06-02 03:04:52 +000019 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +000020 file = sys.stderr
21 for filename, lineno, name, line in extracted_list:
22 _print(file,
23 ' File "%s", line %d, in %s' % (filename,lineno,name))
24 if line:
Eric S. Raymondec3bbde2001-02-09 09:39:08 +000025 _print(file, ' %s' % line.strip())
Guido van Rossumdcc057a1996-08-12 23:18:13 +000026
27def format_list(extracted_list):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000028 """Format a list of traceback entry tuples for printing.
29
30 Given a list of tuples as returned by extract_tb() or
Tim Petersb90f89a2001-01-15 03:26:36 +000031 extract_stack(), return a list of strings ready for printing.
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000032 Each string in the resulting list corresponds to the item with the
33 same index in the argument list. Each string ends in a newline;
34 the strings may contain internal newlines as well, for those items
35 whose source text line is not None.
36 """
Tim Petersb90f89a2001-01-15 03:26:36 +000037 list = []
38 for filename, lineno, name, line in extracted_list:
39 item = ' File "%s", line %d, in %s\n' % (filename,lineno,name)
40 if line:
Eric S. Raymondec3bbde2001-02-09 09:39:08 +000041 item = item + ' %s\n' % line.strip()
Tim Petersb90f89a2001-01-15 03:26:36 +000042 list.append(item)
43 return list
44
Guido van Rossum194e20a1995-09-20 20:31:51 +000045
46def print_tb(tb, limit=None, file=None):
Tim Petersb90f89a2001-01-15 03:26:36 +000047 """Print up to 'limit' stack trace entries from the traceback 'tb'.
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000048
49 If 'limit' is omitted or None, all entries are printed. If 'file'
50 is omitted or None, the output goes to sys.stderr; otherwise
51 'file' should be an open file or file-like object with a write()
52 method.
53 """
Raymond Hettinger10ff7062002-06-02 03:04:52 +000054 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +000055 file = sys.stderr
56 if limit is None:
57 if hasattr(sys, 'tracebacklimit'):
58 limit = sys.tracebacklimit
59 n = 0
60 while tb is not None and (limit is None or n < limit):
61 f = tb.tb_frame
Michael W. Hudsondd32a912002-08-15 14:59:02 +000062 lineno = tb.tb_lineno
Tim Petersb90f89a2001-01-15 03:26:36 +000063 co = f.f_code
64 filename = co.co_filename
65 name = co.co_name
66 _print(file,
67 ' File "%s", line %d, in %s' % (filename,lineno,name))
Hye-Shik Chang182ac852004-10-26 09:16:42 +000068 linecache.checkcache(filename)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +000069 line = linecache.getline(filename, lineno, f.f_globals)
Eric S. Raymondec3bbde2001-02-09 09:39:08 +000070 if line: _print(file, ' ' + line.strip())
Tim Petersb90f89a2001-01-15 03:26:36 +000071 tb = tb.tb_next
72 n = n+1
Guido van Rossum526beed1994-07-01 15:36:46 +000073
Guido van Rossum28e99fe1995-08-04 04:30:30 +000074def format_tb(tb, limit = None):
Tim Petersb90f89a2001-01-15 03:26:36 +000075 """A shorthand for 'format_list(extract_stack(f, limit))."""
76 return format_list(extract_tb(tb, limit))
Guido van Rossum28e99fe1995-08-04 04:30:30 +000077
Guido van Rossum526beed1994-07-01 15:36:46 +000078def extract_tb(tb, limit = None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +000079 """Return list of up to limit pre-processed entries from traceback.
80
81 This is useful for alternate formatting of stack traces. If
82 'limit' is omitted or None, all entries are extracted. A
83 pre-processed stack trace entry is a quadruple (filename, line
84 number, function name, text) representing the information that is
85 usually printed for a stack trace. The text is a string with
86 leading and trailing whitespace stripped; if the source is not
87 available it is None.
88 """
Tim Petersb90f89a2001-01-15 03:26:36 +000089 if limit is None:
90 if hasattr(sys, 'tracebacklimit'):
91 limit = sys.tracebacklimit
92 list = []
93 n = 0
94 while tb is not None and (limit is None or n < limit):
95 f = tb.tb_frame
Michael W. Hudsondd32a912002-08-15 14:59:02 +000096 lineno = tb.tb_lineno
Tim Petersb90f89a2001-01-15 03:26:36 +000097 co = f.f_code
98 filename = co.co_filename
99 name = co.co_name
Hye-Shik Chang182ac852004-10-26 09:16:42 +0000100 linecache.checkcache(filename)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000101 line = linecache.getline(filename, lineno, f.f_globals)
Eric S. Raymondec3bbde2001-02-09 09:39:08 +0000102 if line: line = line.strip()
Tim Petersb90f89a2001-01-15 03:26:36 +0000103 else: line = None
104 list.append((filename, lineno, name, line))
105 tb = tb.tb_next
106 n = n+1
107 return list
Guido van Rossum526beed1994-07-01 15:36:46 +0000108
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000109
Guido van Rossum194e20a1995-09-20 20:31:51 +0000110def print_exception(etype, value, tb, limit=None, file=None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000111 """Print exception up to 'limit' stack trace entries from 'tb' to 'file'.
112
113 This differs from print_tb() in the following ways: (1) if
114 traceback is not None, it prints a header "Traceback (most recent
115 call last):"; (2) it prints the exception type and value after the
116 stack trace; (3) if type is SyntaxError and value has the
117 appropriate format, it prints the line where the syntax error
Tim Petersb90f89a2001-01-15 03:26:36 +0000118 occurred with a caret on the next line indicating the approximate
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000119 position of the error.
120 """
Raymond Hettinger10ff7062002-06-02 03:04:52 +0000121 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +0000122 file = sys.stderr
123 if tb:
124 _print(file, 'Traceback (most recent call last):')
125 print_tb(tb, limit, file)
126 lines = format_exception_only(etype, value)
127 for line in lines[:-1]:
128 _print(file, line, ' ')
129 _print(file, lines[-1], '')
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000130
131def format_exception(etype, value, tb, limit = None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000132 """Format a stack trace and the exception information.
133
134 The arguments have the same meaning as the corresponding arguments
135 to print_exception(). The return value is a list of strings, each
Tim Petersb90f89a2001-01-15 03:26:36 +0000136 ending in a newline and some containing internal newlines. When
137 these lines are concatenated and printed, exactly the same text is
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000138 printed as does print_exception().
139 """
Tim Petersb90f89a2001-01-15 03:26:36 +0000140 if tb:
141 list = ['Traceback (most recent call last):\n']
142 list = list + format_tb(tb, limit)
143 else:
144 list = []
145 list = list + format_exception_only(etype, value)
146 return list
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000147
148def format_exception_only(etype, value):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000149 """Format the exception part of a traceback.
150
151 The arguments are the exception type and value such as given by
152 sys.last_type and sys.last_value. The return value is a list of
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000153 strings, each ending in a newline.
154
155 Normally, the list contains a single string; however, for
156 SyntaxError exceptions, it contains several lines that (when
157 printed) display detailed information about where the syntax
158 error occurred.
159
160 The message indicating which exception occurred is always the last
161 string in the list.
162
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000163 """
Thomas Wouters89f507f2006-12-13 04:49:30 +0000164 # Gracefully handle (the way Python 2.4 and earlier did) the case of
165 # being called with (None, None).
166 if etype is None:
167 return [_format_final_exc_line(etype, value)]
168
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000169 stype = etype.__name__
Guido van Rossum6a2a2a02006-08-26 20:37:44 +0000170 smod = etype.__module__
Neal Norwitz2633c692007-02-26 22:22:47 +0000171 if smod not in ("__main__", "__builtin__"):
Guido van Rossum6a2a2a02006-08-26 20:37:44 +0000172 stype = smod + '.' + stype
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000173
174 if not issubclass(etype, SyntaxError):
175 return [_format_final_exc_line(stype, value)]
176
177 # It was a syntax error; show exactly where the problem was found.
178 lines = []
Guido van Rossum33d26892007-08-05 15:29:28 +0000179 filename = value.filename or "<string>"
180 lineno = str(value.lineno) or '?'
181 lines.append(' File "%s", line %s\n' % (filename, lineno))
182 badline = value.text
183 offset = value.offset
184 if badline is not None:
185 lines.append(' %s\n' % badline.strip())
186 if offset is not None:
187 caretspace = badline[:offset].lstrip()
188 # non-space whitespace (likes tabs) must be kept for alignment
189 caretspace = ((c.isspace() and c or ' ') for c in caretspace)
190 # only three spaces to account for offset1 == pos 0
191 lines.append(' %s^\n' % ''.join(caretspace))
192 msg = value.msg or "<no detail available>"
193 lines.append("%s: %s\n" % (stype, msg))
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000194 return lines
195
196def _format_final_exc_line(etype, value):
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000197 valuestr = _some_str(value)
198 if value is None or not valuestr:
199 line = "%s\n" % etype
Tim Petersb90f89a2001-01-15 03:26:36 +0000200 else:
Thomas Wouters0e3f5912006-08-11 14:57:12 +0000201 line = "%s: %s\n" % (etype, valuestr)
202 return line
Guido van Rossum28e99fe1995-08-04 04:30:30 +0000203
Guido van Rossum2823f032000-08-22 02:04:46 +0000204def _some_str(value):
Tim Petersb90f89a2001-01-15 03:26:36 +0000205 try:
206 return str(value)
207 except:
208 return '<unprintable %s object>' % type(value).__name__
Guido van Rossum2823f032000-08-22 02:04:46 +0000209
Guido van Rossum526beed1994-07-01 15:36:46 +0000210
Guido van Rossum194e20a1995-09-20 20:31:51 +0000211def print_exc(limit=None, file=None):
Neal Norwitzac3625f2006-03-17 05:49:33 +0000212 """Shorthand for 'print_exception(*sys.exc_info(), limit, file)'."""
Raymond Hettinger10ff7062002-06-02 03:04:52 +0000213 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +0000214 file = sys.stderr
215 try:
216 etype, value, tb = sys.exc_info()
217 print_exception(etype, value, tb, limit, file)
218 finally:
219 etype = value = tb = None
Guido van Rossum526beed1994-07-01 15:36:46 +0000220
Neil Schemenauerf607fc52003-11-05 23:03:00 +0000221
222def format_exc(limit=None):
223 """Like print_exc() but return a string."""
224 try:
225 etype, value, tb = sys.exc_info()
226 return ''.join(format_exception(etype, value, tb, limit))
227 finally:
228 etype = value = tb = None
Tim Peters58eb11c2004-01-18 20:29:55 +0000229
Neil Schemenauerf607fc52003-11-05 23:03:00 +0000230
Guido van Rossum194e20a1995-09-20 20:31:51 +0000231def print_last(limit=None, file=None):
Tim Petersb90f89a2001-01-15 03:26:36 +0000232 """This is a shorthand for 'print_exception(sys.last_type,
233 sys.last_value, sys.last_traceback, limit, file)'."""
Raymond Hettinger10ff7062002-06-02 03:04:52 +0000234 if file is None:
Tim Petersb90f89a2001-01-15 03:26:36 +0000235 file = sys.stderr
236 print_exception(sys.last_type, sys.last_value, sys.last_traceback,
237 limit, file)
Guido van Rossumdcc057a1996-08-12 23:18:13 +0000238
239
240def print_stack(f=None, limit=None, file=None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000241 """Print a stack trace from its invocation point.
Tim Petersa19a1682001-03-29 04:36:09 +0000242
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000243 The optional 'f' argument can be used to specify an alternate
244 stack frame at which to start. The optional 'limit' and 'file'
245 arguments have the same meaning as for print_exception().
246 """
Tim Petersb90f89a2001-01-15 03:26:36 +0000247 if f is None:
248 try:
249 raise ZeroDivisionError
250 except ZeroDivisionError:
251 f = sys.exc_info()[2].tb_frame.f_back
252 print_list(extract_stack(f, limit), file)
Guido van Rossumdcc057a1996-08-12 23:18:13 +0000253
254def format_stack(f=None, limit=None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000255 """Shorthand for 'format_list(extract_stack(f, limit))'."""
Tim Petersb90f89a2001-01-15 03:26:36 +0000256 if f is None:
257 try:
258 raise ZeroDivisionError
259 except ZeroDivisionError:
260 f = sys.exc_info()[2].tb_frame.f_back
261 return format_list(extract_stack(f, limit))
Guido van Rossumdcc057a1996-08-12 23:18:13 +0000262
263def extract_stack(f=None, limit = None):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000264 """Extract the raw traceback from the current stack frame.
265
266 The return value has the same format as for extract_tb(). The
267 optional 'f' and 'limit' arguments have the same meaning as for
268 print_stack(). Each item in the list is a quadruple (filename,
269 line number, function name, text), and the entries are in order
270 from oldest to newest stack frame.
271 """
Tim Petersb90f89a2001-01-15 03:26:36 +0000272 if f is None:
273 try:
274 raise ZeroDivisionError
275 except ZeroDivisionError:
276 f = sys.exc_info()[2].tb_frame.f_back
277 if limit is None:
278 if hasattr(sys, 'tracebacklimit'):
279 limit = sys.tracebacklimit
280 list = []
281 n = 0
282 while f is not None and (limit is None or n < limit):
Michael W. Hudsondd32a912002-08-15 14:59:02 +0000283 lineno = f.f_lineno
Tim Petersb90f89a2001-01-15 03:26:36 +0000284 co = f.f_code
285 filename = co.co_filename
286 name = co.co_name
Hye-Shik Chang182ac852004-10-26 09:16:42 +0000287 linecache.checkcache(filename)
Thomas Wouters49fd7fa2006-04-21 10:40:58 +0000288 line = linecache.getline(filename, lineno, f.f_globals)
Eric S. Raymondec3bbde2001-02-09 09:39:08 +0000289 if line: line = line.strip()
Tim Petersb90f89a2001-01-15 03:26:36 +0000290 else: line = None
291 list.append((filename, lineno, name, line))
292 f = f.f_back
293 n = n+1
294 list.reverse()
295 return list
Guido van Rossum47529661997-09-26 22:43:02 +0000296
Guido van Rossum47529661997-09-26 22:43:02 +0000297def tb_lineno(tb):
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000298 """Calculate correct line number of traceback given in tb.
Guido van Rossume7b146f2000-02-04 15:28:42 +0000299
Michael W. Hudsondd32a912002-08-15 14:59:02 +0000300 Obsolete in 2.3.
Jeremy Hylton69e9e8b2001-03-21 19:09:31 +0000301 """
Michael W. Hudsondd32a912002-08-15 14:59:02 +0000302 return tb.tb_lineno