1:mod:`traceback` --- Print or retrieve a stack traceback 2======================================================== 3 4.. module:: traceback 5 :synopsis: Print or retrieve a stack traceback. 6 7 8This module provides a standard interface to extract, format and print stack 9traces of Python programs. It exactly mimics the behavior of the Python 10interpreter when it prints a stack trace. This is useful when you want to print 11stack traces under program control, such as in a "wrapper" around the 12interpreter. 13 14.. index:: object: traceback 15 16The module uses traceback objects --- this is the object type that is stored in 17the variables :data:`sys.exc_traceback` (deprecated) and 18:data:`sys.last_traceback` and returned as the third item from 19:func:`sys.exc_info`. 20 21The module defines the following functions: 22 23 24.. function:: print_tb(tb[, limit[, file]]) 25 26 Print up to *limit* stack trace entries from the traceback object *tb*. If 27 *limit* is omitted or ``None``, all entries are printed. If *file* is omitted 28 or ``None``, the output goes to ``sys.stderr``; otherwise it should be an 29 open file or file-like object to receive the output. 30 31 32.. function:: print_exception(etype, value, tb[, limit[, file]]) 33 34 Print exception information and up to *limit* stack trace entries from the 35 traceback *tb* to *file*. This differs from :func:`print_tb` in the following 36 ways: (1) if *tb* is not ``None``, it prints a header ``Traceback (most 37 recent call last):``; (2) it prints the exception *etype* and *value* after 38 the stack trace; (3) if *etype* is :exc:`SyntaxError` and *value* has the 39 appropriate format, it prints the line where the syntax error occurred with a 40 caret indicating the approximate position of the error. 41 42 43.. function:: print_exc([limit[, file]]) 44 45 This is a shorthand for ``print_exception(sys.exc_type, sys.exc_value, 46 sys.exc_traceback, limit, file)``. (In fact, it uses :func:`sys.exc_info` to 47 retrieve the same information in a thread-safe way instead of using the 48 deprecated variables.) 49 50 51.. function:: format_exc([limit]) 52 53 This is like ``print_exc(limit)`` but returns a string instead of printing to 54 a file. 55 56 .. versionadded:: 2.4 57 58 59.. function:: print_last([limit[, file]]) 60 61 This is a shorthand for ``print_exception(sys.last_type, sys.last_value, 62 sys.last_traceback, limit, file)``. In general it will work only after 63 an exception has reached an interactive prompt (see :data:`sys.last_type`). 64 65 66.. function:: print_stack([f[, limit[, file]]]) 67 68 This function prints a stack trace from its invocation point. The optional 69 *f* argument can be used to specify an alternate stack frame to start. The 70 optional limit* and *file* arguments have the same meaning as for 71 :func:`print_exception`. 72 73 74.. function:: extract_tb(tb[, limit]) 75 76 Return a list of up to *limit* "pre-processed" stack trace entries extracted 77 from the traceback object *tb*. It is useful for alternate formatting of 78 stack traces. If *limit* is omitted or ``None``, all entries are extracted. 79 A "pre-processed" stack trace entry is a 4-tuple (*filename*, *line number*, 80 function name*, *text*) representing the information that is usually printed 81 for a stack trace. The *text* is a string with leading and trailing 82 whitespace stripped; if the source is not available it is ``None``. 83 84 85.. function:: extract_stack([f[, limit]]) 86 87 Extract the raw traceback from the current stack frame. The return value has 88 the same format as for :func:`extract_tb`. The optional *f* and *limit* 89 arguments have the same meaning as for :func:`print_stack`. 90 91 92.. function:: format_list(extracted_list) 93 94 Given a list of tuples as returned by :func:`extract_tb` or 95 :func:`extract_stack`, return a list of strings ready for printing. Each 96 string in the resulting list corresponds to the item with the same index in 97 the argument list. Each string ends in a newline; the strings may contain 98 internal newlines as well, for those items whose source text line is not 99 ``None``. 100 101 102.. function:: format_exception_only(etype, value) 103 104 Format the exception part of a traceback. The arguments are the exception 105 type, *etype* and *value* such as given by ``sys.last_type`` and 106 ``sys.last_value``. The return value is a list of strings, each ending in a 107 newline. Normally, the list contains a single string; however, for 108 :exc:`SyntaxError` exceptions, it contains several lines that (when printed) 109 display detailed information about where the syntax error occurred. The 110 message indicating which exception occurred is the always last string in the 111 list. 112 113 114.. function:: format_exception(etype, value, tb[, limit]) 115 116 Format a stack trace and the exception information. The arguments have the 117 same meaning as the corresponding arguments to :func:`print_exception`. The 118 return value is a list of strings, each ending in a newline and some 119 containing internal newlines. When these lines are concatenated and printed, 120 exactly the same text is printed as does :func:`print_exception`. 121 122 123.. function:: format_tb(tb[, limit]) 124 125 A shorthand for ``format_list(extract_tb(tb, limit))``. 126 127 128.. function:: format_stack([f[, limit]]) 129 130 A shorthand for ``format_list(extract_stack(f, limit))``. 131 132 133.. function:: tb_lineno(tb) 134 135 This function returns the current line number set in the traceback object. 136 This function was necessary because in versions of Python prior to 2.3 when 137 the :option:`-O` flag was passed to Python the ``tb.tb_lineno`` was not 138 updated correctly. This function has no use in versions past 2.3. 139 140 141.. _traceback-example: 142 143Traceback Examples 144------------------ 145 146This simple example implements a basic read-eval-print loop, similar to (but 147less useful than) the standard Python interactive interpreter loop. For a more 148complete implementation of the interpreter loop, refer to the :mod:`code` 149module. :: 150 151 import sys, traceback 152 153 def run_user_code(envdir): 154 source = raw_input(">>> ") 155 try: 156 exec source in envdir 157 except: 158 print "Exception in user code:" 159 print '-'*60 160 traceback.print_exc(file=sys.stdout) 161 print '-'*60 162 163 envdir = {} 164 while 1: 165 run_user_code(envdir) 166 167 168The following example demonstrates the different ways to print and format the 169exception and traceback:: 170 171 import sys, traceback 172 173 def lumberjack(): 174 bright_side_of_death() 175 176 def bright_side_of_death(): 177 return tuple()[0] 178 179 try: 180 lumberjack() 181 except IndexError: 182 exc_type, exc_value, exc_traceback = sys.exc_info() 183 print "*** print_tb:" 184 traceback.print_tb(exc_traceback, limit=1, file=sys.stdout) 185 print "*** print_exception:" 186 traceback.print_exception(exc_type, exc_value, exc_traceback, 187 limit=2, file=sys.stdout) 188 print "*** print_exc:" 189 traceback.print_exc() 190 print "*** format_exc, first and last line:" 191 formatted_lines = traceback.format_exc().splitlines() 192 print formatted_lines[0] 193 print formatted_lines[-1] 194 print "*** format_exception:" 195 print repr(traceback.format_exception(exc_type, exc_value, 196 exc_traceback)) 197 print "*** extract_tb:" 198 print repr(traceback.extract_tb(exc_traceback)) 199 print "*** format_tb:" 200 print repr(traceback.format_tb(exc_traceback)) 201 print "*** tb_lineno:", exc_traceback.tb_lineno 202 203 204The output for the example would look similar to this:: 205 206 *** print_tb: 207 File "<doctest...>", line 10, in <module> 208 lumberjack() 209 *** print_exception: 210 Traceback (most recent call last): 211 File "<doctest...>", line 10, in <module> 212 lumberjack() 213 File "<doctest...>", line 4, in lumberjack 214 bright_side_of_death() 215 IndexError: tuple index out of range 216 *** print_exc: 217 Traceback (most recent call last): 218 File "<doctest...>", line 10, in <module> 219 lumberjack() 220 File "<doctest...>", line 4, in lumberjack 221 bright_side_of_death() 222 IndexError: tuple index out of range 223 *** format_exc, first and last line: 224 Traceback (most recent call last): 225 IndexError: tuple index out of range 226 *** format_exception: 227 ['Traceback (most recent call last):\n', 228 ' File "<doctest...>", line 10, in <module>\n lumberjack()\n', 229 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n', 230 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n', 231 'IndexError: tuple index out of range\n'] 232 *** extract_tb: 233 [('<doctest...>', 10, '<module>', 'lumberjack()'), 234 ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'), 235 ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')] 236 *** format_tb: 237 [' File "<doctest...>", line 10, in <module>\n lumberjack()\n', 238 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n', 239 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n'] 240 *** tb_lineno: 10 241 242 243The following example shows the different ways to print and format the stack:: 244 245 >>> import traceback 246 >>> def another_function(): 247 ... lumberstack() 248 ... 249 >>> def lumberstack(): 250 ... traceback.print_stack() 251 ... print repr(traceback.extract_stack()) 252 ... print repr(traceback.format_stack()) 253 ... 254 >>> another_function() 255 File "<doctest>", line 10, in <module> 256 another_function() 257 File "<doctest>", line 3, in another_function 258 lumberstack() 259 File "<doctest>", line 6, in lumberstack 260 traceback.print_stack() 261 [('<doctest>', 10, '<module>', 'another_function()'), 262 ('<doctest>', 3, 'another_function', 'lumberstack()'), 263 ('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')] 264 [' File "<doctest>", line 10, in <module>\n another_function()\n', 265 ' File "<doctest>", line 3, in another_function\n lumberstack()\n', 266 ' File "<doctest>", line 8, in lumberstack\n print repr(traceback.format_stack())\n'] 267 268 269This last example demonstrates the final few formatting functions: 270 271.. doctest:: 272 :options: +NORMALIZE_WHITESPACE 273 274 >>> import traceback 275 >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'), 276 ... ('eggs.py', 42, 'eggs', 'return "bacon"')]) 277 [' File "spam.py", line 3, in <module>\n spam.eggs()\n', 278 ' File "eggs.py", line 42, in eggs\n return "bacon"\n'] 279 >>> an_error = IndexError('tuple index out of range') 280 >>> traceback.format_exception_only(type(an_error), an_error) 281 ['IndexError: tuple index out of range\n'] 282