1 :mod:`traceback` --- Print or retrieve a stack traceback 2 ======================================================== 3 4 .. module:: traceback 5 :synopsis: Print or retrieve a stack traceback. 6 7 **Source code:** :source:`Lib/traceback.py` 8 9 -------------- 10 11 This module provides a standard interface to extract, format and print stack 12 traces of Python programs. It exactly mimics the behavior of the Python 13 interpreter when it prints a stack trace. This is useful when you want to print 14 stack traces under program control, such as in a "wrapper" around the 15 interpreter. 16 17 .. index:: object: traceback 18 19 The module uses traceback objects --- this is the object type that is stored in 20 the :data:`sys.last_traceback` variable and returned as the third item from 21 :func:`sys.exc_info`. 22 23 The module defines the following functions: 24 25 26 .. function:: print_tb(tb, limit=None, file=None) 27 28 Print up to *limit* stack trace entries from traceback object *tb* (starting 29 from the caller's frame) if *limit* is positive. Otherwise, print the last 30 ``abs(limit)`` entries. If *limit* is omitted or ``None``, all entries are 31 printed. If *file* is omitted or ``None``, the output goes to 32 ``sys.stderr``; otherwise it should be an open file or file-like object to 33 receive the output. 34 35 .. versionchanged:: 3.5 36 Added negative *limit* support. 37 38 39 .. function:: print_exception(etype, value, tb, limit=None, file=None, chain=True) 40 41 Print exception information and stack trace entries from traceback object 42 *tb* to *file*. This differs from :func:`print_tb` in the following 43 ways: 44 45 * if *tb* is not ``None``, it prints a header ``Traceback (most recent 46 call last):`` 47 * it prints the exception *etype* and *value* after the stack trace 48 * if *etype* is :exc:`SyntaxError` and *value* has the appropriate format, it 49 prints the line where the syntax error occurred with a caret indicating the 50 approximate position of the error. 51 52 The optional *limit* argument has the same meaning as for :func:`print_tb`. 53 If *chain* is true (the default), then chained exceptions (the 54 :attr:`__cause__` or :attr:`__context__` attributes of the exception) will be 55 printed as well, like the interpreter itself does when printing an unhandled 56 exception. 57 58 59 .. function:: print_exc(limit=None, file=None, chain=True) 60 61 This is a shorthand for ``print_exception(*sys.exc_info(), limit, file, 62 chain)``. 63 64 65 .. function:: print_last(limit=None, file=None, chain=True) 66 67 This is a shorthand for ``print_exception(sys.last_type, sys.last_value, 68 sys.last_traceback, limit, file, chain)``. In general it will work only 69 after an exception has reached an interactive prompt (see 70 :data:`sys.last_type`). 71 72 73 .. function:: print_stack(f=None, limit=None, file=None) 74 75 Print up to *limit* stack trace entries (starting from the invocation 76 point) if *limit* is positive. Otherwise, print the last ``abs(limit)`` 77 entries. If *limit* is omitted or ``None``, all entries are printed. 78 The optional *f* argument can be used to specify an alternate stack frame 79 to start. The optional *file* argument has the same meaning as for 80 :func:`print_tb`. 81 82 .. versionchanged:: 3.5 83 Added negative *limit* support. 84 85 86 .. function:: extract_tb(tb, limit=None) 87 88 Return a list of "pre-processed" stack trace entries extracted from the 89 traceback object *tb*. It is useful for alternate formatting of 90 stack traces. The optional *limit* argument has the same meaning as for 91 :func:`print_tb`. A "pre-processed" stack trace entry is a 4-tuple 92 (*filename*, *line number*, *function name*, *text*) representing the 93 information that is usually printed for a stack trace. The *text* is a 94 string with leading and trailing whitespace stripped; if the source is 95 not available it is ``None``. 96 97 98 .. function:: extract_stack(f=None, limit=None) 99 100 Extract the raw traceback from the current stack frame. The return value has 101 the same format as for :func:`extract_tb`. The optional *f* and *limit* 102 arguments have the same meaning as for :func:`print_stack`. 103 104 105 .. function:: format_list(extracted_list) 106 107 Given a list of tuples as returned by :func:`extract_tb` or 108 :func:`extract_stack`, return a list of strings ready for printing. Each 109 string in the resulting list corresponds to the item with the same index in 110 the argument list. Each string ends in a newline; the strings may contain 111 internal newlines as well, for those items whose source text line is not 112 ``None``. 113 114 115 .. function:: format_exception_only(etype, value) 116 117 Format the exception part of a traceback. The arguments are the exception 118 type and value such as given by ``sys.last_type`` and ``sys.last_value``. 119 The return value is a list of strings, each ending in a newline. Normally, 120 the list contains a single string; however, for :exc:`SyntaxError` 121 exceptions, it contains several lines that (when printed) display detailed 122 information about where the syntax error occurred. The message indicating 123 which exception occurred is the always last string in the list. 124 125 126 .. function:: format_exception(etype, value, tb, limit=None, chain=True) 127 128 Format a stack trace and the exception information. The arguments have the 129 same meaning as the corresponding arguments to :func:`print_exception`. The 130 return value is a list of strings, each ending in a newline and some 131 containing internal newlines. When these lines are concatenated and printed, 132 exactly the same text is printed as does :func:`print_exception`. 133 134 135 .. function:: format_exc(limit=None, chain=True) 136 137 This is like ``print_exc(limit)`` but returns a string instead of printing to 138 a file. 139 140 141 .. function:: format_tb(tb, limit=None) 142 143 A shorthand for ``format_list(extract_tb(tb, limit))``. 144 145 146 .. function:: format_stack(f=None, limit=None) 147 148 A shorthand for ``format_list(extract_stack(f, limit))``. 149 150 .. function:: clear_frames(tb) 151 152 Clears the local variables of all the stack frames in a traceback *tb* 153 by calling the :meth:`clear` method of each frame object. 154 155 .. versionadded:: 3.4 156 157 .. function:: walk_stack(f) 158 159 Walk a stack following ``f.f_back`` from the given frame, yielding the frame 160 and line number for each frame. If *f* is ``None``, the current stack is 161 used. This helper is used with :meth:`StackSummary.extract`. 162 163 .. versionadded:: 3.5 164 165 .. function:: walk_tb(tb) 166 167 Walk a traceback following ``tb_next`` yielding the frame and line number 168 for each frame. This helper is used with :meth:`StackSummary.extract`. 169 170 .. versionadded:: 3.5 171 172 The module also defines the following classes: 173 174 :class:`TracebackException` Objects 175 ----------------------------------- 176 177 .. versionadded:: 3.5 178 179 :class:`TracebackException` objects are created from actual exceptions to 180 capture data for later printing in a lightweight fashion. 181 182 .. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False) 183 184 Capture an exception for later rendering. *limit*, *lookup_lines* and 185 *capture_locals* are as for the :class:`StackSummary` class. 186 187 Note that when locals are captured, they are also shown in the traceback. 188 189 .. attribute:: __cause__ 190 191 A :class:`TracebackException` of the original ``__cause__``. 192 193 .. attribute:: __context__ 194 195 A :class:`TracebackException` of the original ``__context__``. 196 197 .. attribute:: __suppress_context__ 198 199 The ``__suppress_context__`` value from the original exception. 200 201 .. attribute:: stack 202 203 A :class:`StackSummary` representing the traceback. 204 205 .. attribute:: exc_type 206 207 The class of the original traceback. 208 209 .. attribute:: filename 210 211 For syntax errors - the file name where the error occurred. 212 213 .. attribute:: lineno 214 215 For syntax errors - the line number where the error occurred. 216 217 .. attribute:: text 218 219 For syntax errors - the text where the error occurred. 220 221 .. attribute:: offset 222 223 For syntax errors - the offset into the text where the error occurred. 224 225 .. attribute:: msg 226 227 For syntax errors - the compiler error message. 228 229 .. classmethod:: from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False) 230 231 Capture an exception for later rendering. *limit*, *lookup_lines* and 232 *capture_locals* are as for the :class:`StackSummary` class. 233 234 Note that when locals are captured, they are also shown in the traceback. 235 236 .. method:: format(*, chain=True) 237 238 Format the exception. 239 240 If *chain* is not ``True``, ``__cause__`` and ``__context__`` will not 241 be formatted. 242 243 The return value is a generator of strings, each ending in a newline and 244 some containing internal newlines. :func:`~traceback.print_exception` 245 is a wrapper around this method which just prints the lines to a file. 246 247 The message indicating which exception occurred is always the last 248 string in the output. 249 250 .. method:: format_exception_only() 251 252 Format the exception part of the traceback. 253 254 The return value is a generator of strings, each ending in a newline. 255 256 Normally, the generator emits a single string; however, for 257 :exc:`SyntaxError` exceptions, it emits several lines that (when 258 printed) display detailed information about where the syntax 259 error occurred. 260 261 The message indicating which exception occurred is always the last 262 string in the output. 263 264 265 :class:`StackSummary` Objects 266 ----------------------------- 267 268 .. versionadded:: 3.5 269 270 :class:`StackSummary` objects represent a call stack ready for formatting. 271 272 .. class:: StackSummary 273 274 .. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False) 275 276 Construct a :class:`StackSummary` object from a frame generator (such as 277 is returned by :func:`~traceback.walk_stack` or 278 :func:`~traceback.walk_tb`). 279 280 If *limit* is supplied, only this many frames are taken from *frame_gen*. 281 If *lookup_lines* is ``False``, the returned :class:`FrameSummary` 282 objects will not have read their lines in yet, making the cost of 283 creating the :class:`StackSummary` cheaper (which may be valuable if it 284 may not actually get formatted). If *capture_locals* is ``True`` the 285 local variables in each :class:`FrameSummary` are captured as object 286 representations. 287 288 .. classmethod:: from_list(a_list) 289 290 Construct a :class:`StackSummary` object from a supplied old-style list 291 of tuples. Each tuple should be a 4-tuple with filename, lineno, name, 292 line as the elements. 293 294 .. method:: format() 295 296 Returns a list of strings ready for printing. Each string in the 297 resulting list corresponds to a single frame from the stack. 298 Each string ends in a newline; the strings may contain internal 299 newlines as well, for those items with source text lines. 300 301 For long sequences of the same frame and line, the first few 302 repetitions are shown, followed by a summary line stating the exact 303 number of further repetitions. 304 305 .. versionchanged:: 3.6 306 Long sequences of repeated frames are now abbreviated. 307 308 309 :class:`FrameSummary` Objects 310 ----------------------------- 311 312 .. versionadded:: 3.5 313 314 :class:`FrameSummary` objects represent a single frame in a traceback. 315 316 .. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None) 317 318 Represent a single frame in the traceback or stack that is being formatted 319 or printed. It may optionally have a stringified version of the frames 320 locals included in it. If *lookup_line* is ``False``, the source code is not 321 looked up until the :class:`FrameSummary` has the :attr:`~FrameSummary.line` 322 attribute accessed (which also happens when casting it to a tuple). 323 :attr:`~FrameSummary.line` may be directly provided, and will prevent line 324 lookups happening at all. *locals* is an optional local variable 325 dictionary, and if supplied the variable representations are stored in the 326 summary for later display. 327 328 .. _traceback-example: 329 330 Traceback Examples 331 ------------------ 332 333 This simple example implements a basic read-eval-print loop, similar to (but 334 less useful than) the standard Python interactive interpreter loop. For a more 335 complete implementation of the interpreter loop, refer to the :mod:`code` 336 module. :: 337 338 import sys, traceback 339 340 def run_user_code(envdir): 341 source = input(">>> ") 342 try: 343 exec(source, envdir) 344 except Exception: 345 print("Exception in user code:") 346 print("-"*60) 347 traceback.print_exc(file=sys.stdout) 348 print("-"*60) 349 350 envdir = {} 351 while True: 352 run_user_code(envdir) 353 354 355 The following example demonstrates the different ways to print and format the 356 exception and traceback: 357 358 .. testcode:: 359 360 import sys, traceback 361 362 def lumberjack(): 363 bright_side_of_death() 364 365 def bright_side_of_death(): 366 return tuple()[0] 367 368 try: 369 lumberjack() 370 except IndexError: 371 exc_type, exc_value, exc_traceback = sys.exc_info() 372 print("*** print_tb:") 373 traceback.print_tb(exc_traceback, limit=1, file=sys.stdout) 374 print("*** print_exception:") 375 traceback.print_exception(exc_type, exc_value, exc_traceback, 376 limit=2, file=sys.stdout) 377 print("*** print_exc:") 378 traceback.print_exc(limit=2, file=sys.stdout) 379 print("*** format_exc, first and last line:") 380 formatted_lines = traceback.format_exc().splitlines() 381 print(formatted_lines[0]) 382 print(formatted_lines[-1]) 383 print("*** format_exception:") 384 print(repr(traceback.format_exception(exc_type, exc_value, 385 exc_traceback))) 386 print("*** extract_tb:") 387 print(repr(traceback.extract_tb(exc_traceback))) 388 print("*** format_tb:") 389 print(repr(traceback.format_tb(exc_traceback))) 390 print("*** tb_lineno:", exc_traceback.tb_lineno) 391 392 The output for the example would look similar to this: 393 394 .. testoutput:: 395 :options: +NORMALIZE_WHITESPACE 396 397 *** print_tb: 398 File "<doctest...>", line 10, in <module> 399 lumberjack() 400 *** print_exception: 401 Traceback (most recent call last): 402 File "<doctest...>", line 10, in <module> 403 lumberjack() 404 File "<doctest...>", line 4, in lumberjack 405 bright_side_of_death() 406 IndexError: tuple index out of range 407 *** print_exc: 408 Traceback (most recent call last): 409 File "<doctest...>", line 10, in <module> 410 lumberjack() 411 File "<doctest...>", line 4, in lumberjack 412 bright_side_of_death() 413 IndexError: tuple index out of range 414 *** format_exc, first and last line: 415 Traceback (most recent call last): 416 IndexError: tuple index out of range 417 *** format_exception: 418 ['Traceback (most recent call last):\n', 419 ' File "<doctest...>", line 10, in <module>\n lumberjack()\n', 420 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n', 421 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n', 422 'IndexError: tuple index out of range\n'] 423 *** extract_tb: 424 [<FrameSummary file <doctest...>, line 10 in <module>>, 425 <FrameSummary file <doctest...>, line 4 in lumberjack>, 426 <FrameSummary file <doctest...>, line 7 in bright_side_of_death>] 427 *** format_tb: 428 [' File "<doctest...>", line 10, in <module>\n lumberjack()\n', 429 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n', 430 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n'] 431 *** tb_lineno: 10 432 433 434 The following example shows the different ways to print and format the stack:: 435 436 >>> import traceback 437 >>> def another_function(): 438 ... lumberstack() 439 ... 440 >>> def lumberstack(): 441 ... traceback.print_stack() 442 ... print(repr(traceback.extract_stack())) 443 ... print(repr(traceback.format_stack())) 444 ... 445 >>> another_function() 446 File "<doctest>", line 10, in <module> 447 another_function() 448 File "<doctest>", line 3, in another_function 449 lumberstack() 450 File "<doctest>", line 6, in lumberstack 451 traceback.print_stack() 452 [('<doctest>', 10, '<module>', 'another_function()'), 453 ('<doctest>', 3, 'another_function', 'lumberstack()'), 454 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')] 455 [' File "<doctest>", line 10, in <module>\n another_function()\n', 456 ' File "<doctest>", line 3, in another_function\n lumberstack()\n', 457 ' File "<doctest>", line 8, in lumberstack\n print(repr(traceback.format_stack()))\n'] 458 459 460 This last example demonstrates the final few formatting functions: 461 462 .. doctest:: 463 :options: +NORMALIZE_WHITESPACE 464 465 >>> import traceback 466 >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'), 467 ... ('eggs.py', 42, 'eggs', 'return "bacon"')]) 468 [' File "spam.py", line 3, in <module>\n spam.eggs()\n', 469 ' File "eggs.py", line 42, in eggs\n return "bacon"\n'] 470 >>> an_error = IndexError('tuple index out of range') 471 >>> traceback.format_exception_only(type(an_error), an_error) 472 ['IndexError: tuple index out of range\n'] 473
