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