1
:mod:`traceback` --- Print or retrieve a stack traceback
2
========================================================
5
:synopsis: Print or retrieve a stack traceback.
8
This module provides a standard interface to extract, format and print stack
9
traces of Python programs. It exactly mimics the behavior of the Python
10
interpreter when it prints a stack trace. This is useful when you want to print
11
stack traces under program control, such as in a "wrapper" around the
14
.. index:: object: traceback
16
The module uses traceback objects --- this is the object type that is stored in
17
the :data:`sys.last_traceback` variable and returned as the third item from
20
The module defines the following functions:
23
.. function:: print_tb(tb, limit=None, file=None)
25
Print up to *limit* stack trace entries from traceback object *tb* (starting
26
from the caller's frame) if *limit* is positive. Otherwise, print the last
27
``abs(limit)`` entries. If *limit* is omitted or ``None``, all entries are
28
printed. If *file* is omitted or ``None``, the output goes to
29
``sys.stderr``; otherwise it should be an open file or file-like object to
32
.. versionchanged:: 3.5
33
Added negative *limit* support.
36
.. function:: print_exception(etype, value, tb, limit=None, file=None, chain=True)
38
Print exception information and stack trace entries from traceback object
39
*tb* to *file*. This differs from :func:`print_tb` in the following
42
* if *tb* is not ``None``, it prints a header ``Traceback (most recent
44
* it prints the exception *etype* and *value* after the stack trace
45
* if *etype* is :exc:`SyntaxError` and *value* has the appropriate format, it
46
prints the line where the syntax error occurred with a caret indicating the
47
approximate position of the error.
49
The optional *limit* argument has the same meaning as for :func:`print_tb`.
50
If *chain* is true (the default), then chained exceptions (the
51
:attr:`__cause__` or :attr:`__context__` attributes of the exception) will be
52
printed as well, like the interpreter itself does when printing an unhandled
56
.. function:: print_exc(limit=None, file=None, chain=True)
58
This is a shorthand for ``print_exception(*sys.exc_info(), limit, file,
62
.. function:: print_last(limit=None, file=None, chain=True)
64
This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
65
sys.last_traceback, limit, file, chain)``. In general it will work only
66
after an exception has reached an interactive prompt (see
67
:data:`sys.last_type`).
70
.. function:: print_stack(f=None, limit=None, file=None)
72
Print up to *limit* stack trace entries (starting from the invocation
73
point) if *limit* is positive. Otherwise, print the last ``abs(limit)``
74
entries. If *limit* is omitted or ``None``, all entries are printed.
75
The optional *f* argument can be used to specify an alternate stack frame
76
to start. The optional *file* argument has the same meaning as for
79
.. versionchanged:: 3.5
80
Added negative *limit* support.
83
.. function:: extract_tb(tb, limit=None)
85
Return a list of "pre-processed" stack trace entries extracted from the
86
traceback object *tb*. It is useful for alternate formatting of
87
stack traces. The optional *limit* argument has the same meaning as for
88
:func:`print_tb`. A "pre-processed" stack trace entry is a 4-tuple
89
(*filename*, *line number*, *function name*, *text*) representing the
90
information that is usually printed for a stack trace. The *text* is a
91
string with leading and trailing whitespace stripped; if the source is
92
not available it is ``None``.
95
.. function:: extract_stack(f=None, limit=None)
97
Extract the raw traceback from the current stack frame. The return value has
98
the same format as for :func:`extract_tb`. The optional *f* and *limit*
99
arguments have the same meaning as for :func:`print_stack`.
102
.. function:: format_list(extracted_list)
104
Given a list of tuples as returned by :func:`extract_tb` or
105
:func:`extract_stack`, return a list of strings ready for printing. Each
106
string in the resulting list corresponds to the item with the same index in
107
the argument list. Each string ends in a newline; the strings may contain
108
internal newlines as well, for those items whose source text line is not
112
.. function:: format_exception_only(etype, value)
114
Format the exception part of a traceback. The arguments are the exception
115
type and value such as given by ``sys.last_type`` and ``sys.last_value``.
116
The return value is a list of strings, each ending in a newline. Normally,
117
the list contains a single string; however, for :exc:`SyntaxError`
118
exceptions, it contains several lines that (when printed) display detailed
119
information about where the syntax error occurred. The message indicating
120
which exception occurred is the always last string in the list.
123
.. function:: format_exception(etype, value, tb, limit=None, chain=True)
125
Format a stack trace and the exception information. The arguments have the
126
same meaning as the corresponding arguments to :func:`print_exception`. The
127
return value is a list of strings, each ending in a newline and some
128
containing internal newlines. When these lines are concatenated and printed,
129
exactly the same text is printed as does :func:`print_exception`.
132
.. function:: format_exc(limit=None, chain=True)
134
This is like ``print_exc(limit)`` but returns a string instead of printing to
138
.. function:: format_tb(tb, limit=None)
140
A shorthand for ``format_list(extract_tb(tb, limit))``.
143
.. function:: format_stack(f=None, limit=None)
145
A shorthand for ``format_list(extract_stack(f, limit))``.
147
.. function:: clear_frames(tb)
149
Clears the local variables of all the stack frames in a traceback *tb*
150
by calling the :meth:`clear` method of each frame object.
152
.. versionadded:: 3.4
154
.. function:: walk_stack(f)
156
Walk a stack following ``f.f_back`` from the given frame, yielding the frame
157
and line number for each frame. If *f* is ``None``, the current stack is
158
used. This helper is used with :meth:`StackSummary.extract`.
160
.. versionadded:: 3.5
162
.. function:: walk_tb(tb)
164
Walk a traceback following ``tb_next`` yielding the frame and line number
165
for each frame. This helper is used with :meth:`StackSummary.extract`.
167
.. versionadded:: 3.5
169
The module also defines the following classes:
171
:class:`TracebackException` Objects
172
-----------------------------------
174
.. versionadded:: 3.5
176
:class:`TracebackException` objects are created from actual exceptions to
177
capture data for later printing in a lightweight fashion.
179
.. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False)
181
Capture an exception for later rendering. *limit*, *lookup_lines* and
182
*capture_locals* are as for the :class:`StackSummary` class.
184
Note that when locals are captured, they are also shown in the traceback.
186
.. attribute:: __cause__
188
A :class:`TracebackException` of the original ``__cause__``.
190
.. attribute:: __context__
192
A :class:`TracebackException` of the original ``__context__``.
194
.. attribute:: __suppress_context__
196
The ``__suppress_context__`` value from the original exception.
200
A :class:`StackSummary` representing the traceback.
202
.. attribute:: exc_type
204
The class of the original traceback.
206
.. attribute:: filename
208
For syntax errors - the file name where the error occurred.
210
.. attribute:: lineno
212
For syntax errors - the line number where the error occurred.
216
For syntax errors - the text where the error occurred.
218
.. attribute:: offset
220
For syntax errors - the offset into the text where the error occurred.
224
For syntax errors - the compiler error message.
226
.. classmethod:: from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)
228
Capture an exception for later rendering. *limit*, *lookup_lines* and
229
*capture_locals* are as for the :class:`StackSummary` class.
231
Note that when locals are captured, they are also shown in the traceback.
233
.. method:: format(*, chain=True)
235
Format the exception.
237
If *chain* is not ``True``, ``__cause__`` and ``__context__`` will not
240
The return value is a generator of strings, each ending in a newline and
241
some containing internal newlines. :func:`~traceback.print_exception`
242
is a wrapper around this method which just prints the lines to a file.
244
The message indicating which exception occurred is always the last
245
string in the output.
247
.. method:: format_exception_only()
249
Format the exception part of the traceback.
251
The return value is a generator of strings, each ending in a newline.
253
Normally, the generator emits a single string; however, for
254
:exc:`SyntaxError` exceptions, it emits several lines that (when
255
printed) display detailed information about where the syntax
258
The message indicating which exception occurred is always the last
259
string in the output.
262
:class:`StackSummary` Objects
263
-----------------------------
265
.. versionadded:: 3.5
267
:class:`StackSummary` objects represent a call stack ready for formatting.
269
.. class:: StackSummary
271
.. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)
273
Construct a :class:`StackSummary` object from a frame generator (such as
274
is returned by :func:`~traceback.walk_stack` or
275
:func:`~traceback.walk_tb`).
277
If *limit* is supplied, only this many frames are taken from *frame_gen*.
278
If *lookup_lines* is ``False``, the returned :class:`FrameSummary`
279
objects will not have read their lines in yet, making the cost of
280
creating the :class:`StackSummary` cheaper (which may be valuable if it
281
may not actually get formatted). If *capture_locals* is ``True`` the
282
local variables in each :class:`FrameSummary` are captured as object
285
.. classmethod:: from_list(a_list)
287
Construct a :class:`StackSummary` object from a supplied old-style list
288
of tuples. Each tuple should be a 4-tuple with filename, lineno, name,
289
line as the elements.
292
:class:`FrameSummary` Objects
293
-----------------------------
295
.. versionadded:: 3.5
297
:class:`FrameSummary` objects represent a single frame in a traceback.
299
.. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)
301
Represent a single frame in the traceback or stack that is being formatted
302
or printed. It may optionally have a stringified version of the frames
303
locals included in it. If *lookup_line* is ``False``, the source code is not
304
looked up until the :class:`FrameSummary` has the :attr:`~FrameSummary.line`
305
attribute accessed (which also happens when casting it to a tuple).
306
:attr:`~FrameSummary.line` may be directly provided, and will prevent line
307
lookups happening at all. *locals* is an optional local variable
308
dictionary, and if supplied the variable representations are stored in the
309
summary for later display.
311
.. _traceback-example:
316
This simple example implements a basic read-eval-print loop, similar to (but
317
less useful than) the standard Python interactive interpreter loop. For a more
318
complete implementation of the interpreter loop, refer to the :mod:`code`
321
import sys, traceback
323
def run_user_code(envdir):
324
source = input(">>> ")
328
print("Exception in user code:")
330
traceback.print_exc(file=sys.stdout)
335
run_user_code(envdir)
338
The following example demonstrates the different ways to print and format the
339
exception and traceback:
343
import sys, traceback
346
bright_side_of_death()
348
def bright_side_of_death():
354
exc_type, exc_value, exc_traceback = sys.exc_info()
355
print("*** print_tb:")
356
traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
357
print("*** print_exception:")
358
traceback.print_exception(exc_type, exc_value, exc_traceback,
359
limit=2, file=sys.stdout)
360
print("*** print_exc:")
361
traceback.print_exc()
362
print("*** format_exc, first and last line:")
363
formatted_lines = traceback.format_exc().splitlines()
364
print(formatted_lines[0])
365
print(formatted_lines[-1])
366
print("*** format_exception:")
367
print(repr(traceback.format_exception(exc_type, exc_value,
369
print("*** extract_tb:")
370
print(repr(traceback.extract_tb(exc_traceback)))
371
print("*** format_tb:")
372
print(repr(traceback.format_tb(exc_traceback)))
373
print("*** tb_lineno:", exc_traceback.tb_lineno)
375
The output for the example would look similar to this:
378
:options: +NORMALIZE_WHITESPACE
381
File "<doctest...>", line 10, in <module>
384
Traceback (most recent call last):
385
File "<doctest...>", line 10, in <module>
387
File "<doctest...>", line 4, in lumberjack
388
bright_side_of_death()
389
IndexError: tuple index out of range
391
Traceback (most recent call last):
392
File "<doctest...>", line 10, in <module>
394
File "<doctest...>", line 4, in lumberjack
395
bright_side_of_death()
396
IndexError: tuple index out of range
397
*** format_exc, first and last line:
398
Traceback (most recent call last):
399
IndexError: tuple index out of range
400
*** format_exception:
401
['Traceback (most recent call last):\n',
402
' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
403
' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
404
' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n',
405
'IndexError: tuple index out of range\n']
407
[('<doctest...>', 10, '<module>', 'lumberjack()'),
408
('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
409
('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
411
[' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
412
' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
413
' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n']
417
The following example shows the different ways to print and format the stack::
420
>>> def another_function():
423
>>> def lumberstack():
424
... traceback.print_stack()
425
... print(repr(traceback.extract_stack()))
426
... print(repr(traceback.format_stack()))
428
>>> another_function()
429
File "<doctest>", line 10, in <module>
431
File "<doctest>", line 3, in another_function
433
File "<doctest>", line 6, in lumberstack
434
traceback.print_stack()
435
[('<doctest>', 10, '<module>', 'another_function()'),
436
('<doctest>', 3, 'another_function', 'lumberstack()'),
437
('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
438
[' File "<doctest>", line 10, in <module>\n another_function()\n',
439
' File "<doctest>", line 3, in another_function\n lumberstack()\n',
440
' File "<doctest>", line 8, in lumberstack\n print(repr(traceback.format_stack()))\n']
443
This last example demonstrates the final few formatting functions:
446
:options: +NORMALIZE_WHITESPACE
449
>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
450
... ('eggs.py', 42, 'eggs', 'return "bacon"')])
451
[' File "spam.py", line 3, in <module>\n spam.eggs()\n',
452
' File "eggs.py", line 42, in eggs\n return "bacon"\n']
453
>>> an_error = IndexError('tuple index out of range')
454
>>> traceback.format_exception_only(type(an_error), an_error)
455
['IndexError: tuple index out of range\n']
added
removed
python-3.5.1-docs-html/_sources/library/traceback.txt
