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 variables :data:`sys.exc_traceback` (deprecated) and :data:`sys.last_traceback` and
18 returned as the third item from :func:`sys.exc_info`.
20 The module defines the following functions:
23 .. function:: print_tb(traceback[, limit[, file]])
25 Print up to *limit* stack trace entries from *traceback*. If *limit* is omitted
26 or ``None``, all entries are printed. If *file* is omitted or ``None``, the
27 output goes to ``sys.stderr``; otherwise it should be an open file or file-like
28 object to receive the output.
31 .. function:: print_exception(type, value, traceback[, limit[, file]])
33 Print exception information and up to *limit* stack trace entries from
34 *traceback* to *file*. This differs from :func:`print_tb` in the following ways:
35 (1) if *traceback* is not ``None``, it prints a header ``Traceback (most recent
36 call last):``; (2) it prints the exception *type* and *value* after the stack
37 trace; (3) if *type* is :exc:`SyntaxError` and *value* has the appropriate
38 format, it prints the line where the syntax error occurred with a caret
39 indicating the approximate position of the error.
42 .. function:: print_exc([limit[, file]])
44 This is a shorthand for ``print_exception(sys.exc_type, sys.exc_value,
45 sys.exc_traceback, limit, file)``. (In fact, it uses :func:`sys.exc_info` to
46 retrieve the same information in a thread-safe way instead of using the
47 deprecated variables.)
50 .. function:: format_exc([limit])
52 This is like ``print_exc(limit)`` but returns a string instead of printing to a
58 .. function:: print_last([limit[, file]])
60 This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
61 sys.last_traceback, limit, file)``. In general it will work only after
62 an exception has reached an interactive prompt (see :data:`sys.last_type`).
65 .. function:: print_stack([f[, limit[, file]]])
67 This function prints a stack trace from its invocation point. The optional *f*
68 argument can be used to specify an alternate stack frame to start. The optional
69 *limit* and *file* arguments have the same meaning as for
70 :func:`print_exception`.
73 .. function:: extract_tb(traceback[, limit])
75 Return a list of up to *limit* "pre-processed" stack trace entries extracted
76 from the traceback object *traceback*. It is useful for alternate formatting of
77 stack traces. If *limit* is omitted or ``None``, all entries are extracted. A
78 "pre-processed" stack trace entry is a quadruple (*filename*, *line number*,
79 *function name*, *text*) representing the information that is usually printed
80 for a stack trace. The *text* is a string with leading and trailing whitespace
81 stripped; if the source is not available it is ``None``.
84 .. function:: extract_stack([f[, limit]])
86 Extract the raw traceback from the current stack frame. The return value has
87 the same format as for :func:`extract_tb`. The optional *f* and *limit*
88 arguments have the same meaning as for :func:`print_stack`.
91 .. function:: format_list(list)
93 Given a list of tuples as returned by :func:`extract_tb` or
94 :func:`extract_stack`, return a list of strings ready for printing. Each string
95 in the resulting list corresponds to the item with the same index in the
96 argument list. Each string ends in a newline; the strings may contain internal
97 newlines as well, for those items whose source text line is not ``None``.
100 .. function:: format_exception_only(type, value)
102 Format the exception part of a traceback. The arguments are the exception type
103 and value such as given by ``sys.last_type`` and ``sys.last_value``. The return
104 value is a list of strings, each ending in a newline. Normally, the list
105 contains a single string; however, for :exc:`SyntaxError` exceptions, it
106 contains several lines that (when printed) display detailed information about
107 where the syntax error occurred. The message indicating which exception
108 occurred is the always last string in the list.
111 .. function:: format_exception(type, value, tb[, limit])
113 Format a stack trace and the exception information. The arguments have the
114 same meaning as the corresponding arguments to :func:`print_exception`. The
115 return value is a list of strings, each ending in a newline and some containing
116 internal newlines. When these lines are concatenated and printed, exactly the
117 same text is printed as does :func:`print_exception`.
120 .. function:: format_tb(tb[, limit])
122 A shorthand for ``format_list(extract_tb(tb, limit))``.
125 .. function:: format_stack([f[, limit]])
127 A shorthand for ``format_list(extract_stack(f, limit))``.
130 .. function:: tb_lineno(tb)
132 This function returns the current line number set in the traceback object. This
133 function was necessary because in versions of Python prior to 2.3 when the
134 :option:`-O` flag was passed to Python the ``tb.tb_lineno`` was not updated
135 correctly. This function has no use in versions past 2.3.
138 .. _traceback-example:
143 This simple example implements a basic read-eval-print loop, similar to (but
144 less useful than) the standard Python interactive interpreter loop. For a more
145 complete implementation of the interpreter loop, refer to the :mod:`code`
148 import sys, traceback
150 def run_user_code(envdir):
151 source = raw_input(">>> ")
153 exec source in envdir
155 print "Exception in user code:"
157 traceback.print_exc(file=sys.stdout)
162 run_user_code(envdir)
165 The following example demonstrates the different ways to print and format the
166 exception and traceback::
168 import sys, traceback
171 bright_side_of_death()
173 def bright_side_of_death():
179 exceptionType, exceptionValue, exceptionTraceback = sys.exc_info()
180 print "*** print_tb:"
181 traceback.print_tb(exceptionTraceback, limit=1, file=sys.stdout)
182 print "*** print_exception:"
183 traceback.print_exception(exceptionType, exceptionValue, exceptionTraceback,
184 limit=2, file=sys.stdout)
185 print "*** print_exc:"
186 traceback.print_exc()
187 print "*** format_exc, first and last line:"
188 formatted_lines = traceback.format_exc().splitlines()
189 print formatted_lines[0]
190 print formatted_lines[-1]
191 print "*** format_exception:"
192 print repr(traceback.format_exception(exceptionType, exceptionValue,
194 print "*** extract_tb:"
195 print repr(traceback.extract_tb(exceptionTraceback))
196 print "*** format_tb:"
197 print repr(traceback.format_tb(exceptionTraceback))
198 print "*** tb_lineno:", traceback.tb_lineno(exceptionTraceback)
201 The output for the example would look similar to this::
204 File "<doctest...>", line 10, in <module>
207 Traceback (most recent call last):
208 File "<doctest...>", line 10, in <module>
210 File "<doctest...>", line 4, in lumberjack
211 bright_side_of_death()
212 IndexError: tuple index out of range
214 Traceback (most recent call last):
215 File "<doctest...>", line 10, in <module>
217 File "<doctest...>", line 4, in lumberjack
218 bright_side_of_death()
219 IndexError: tuple index out of range
220 *** format_exc, first and last line:
221 Traceback (most recent call last):
222 IndexError: tuple index out of range
223 *** format_exception:
224 ['Traceback (most recent call last):\n',
225 ' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
226 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
227 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n',
228 'IndexError: tuple index out of range\n']
230 [('<doctest...>', 10, '<module>', 'lumberjack()'),
231 ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
232 ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
234 [' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
235 ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
236 ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n']
240 The following example shows the different ways to print and format the stack::
243 >>> def another_function():
246 >>> def lumberstack():
247 ... traceback.print_stack()
248 ... print repr(traceback.extract_stack())
249 ... print repr(traceback.format_stack())
251 >>> another_function()
252 File "<doctest>", line 10, in <module>
254 File "<doctest>", line 3, in another_function
256 File "<doctest>", line 6, in lumberstack
257 traceback.print_stack()
258 [('<doctest>', 10, '<module>', 'another_function()'),
259 ('<doctest>', 3, 'another_function', 'lumberstack()'),
260 ('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')]
261 [' File "<doctest>", line 10, in <module>\n another_function()\n',
262 ' File "<doctest>", line 3, in another_function\n lumberstack()\n',
263 ' File "<doctest>", line 8, in lumberstack\n print repr(traceback.format_stack())\n']
266 This last example demonstrates the final few formatting functions:
269 :options: +NORMALIZE_WHITESPACE
272 >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
273 ... ('eggs.py', 42, 'eggs', 'return "bacon"')])
274 [' File "spam.py", line 3, in <module>\n spam.eggs()\n',
275 ' File "eggs.py", line 42, in eggs\n return "bacon"\n']
276 >>> an_error = IndexError('tuple index out of range')
277 >>> traceback.format_exception_only(type(an_error), an_error)
278 ['IndexError: tuple index out of range\n']