/Doc/library/traceback.rst

  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 :data:`sys.last_traceback` and
 18returned as the third item from :func:`sys.exc_info`.
 19
 20The module defines the following functions:
 21
 22
 23.. function:: print_tb(traceback[, limit[, file]])
 24
 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.
 29
 30
 31.. function:: print_exception(type, value, traceback[, limit[, file]])
 32
 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.
 40
 41
 42.. function:: print_exc([limit[, file]])
 43
 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.)
 48
 49
 50.. function:: format_exc([limit])
 51
 52   This is like ``print_exc(limit)`` but returns a string instead of printing to a
 53   file.
 54
 55   .. versionadded:: 2.4
 56
 57
 58.. function:: print_last([limit[, file]])
 59
 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`).
 63
 64
 65.. function:: print_stack([f[, limit[, file]]])
 66
 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`.
 71
 72
 73.. function:: extract_tb(traceback[, limit])
 74
 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``.
 82
 83
 84.. function:: extract_stack([f[, limit]])
 85
 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`.
 89
 90
 91.. function:: format_list(list)
 92
 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``.
 98
 99
100.. function:: format_exception_only(type, value)
101
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.
109
110
111.. function:: format_exception(type, value, tb[, limit])
112
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`.
118
119
120.. function:: format_tb(tb[, limit])
121
122   A shorthand for ``format_list(extract_tb(tb, limit))``.
123
124
125.. function:: format_stack([f[, limit]])
126
127   A shorthand for ``format_list(extract_stack(f, limit))``.
128
129
130.. function:: tb_lineno(tb)
131
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.
136
137
138.. _traceback-example:
139
140Traceback Examples
141------------------
142
143This simple example implements a basic read-eval-print loop, similar to (but
144less useful than) the standard Python interactive interpreter loop.  For a more
145complete implementation of the interpreter loop, refer to the :mod:`code`
146module. ::
147
148   import sys, traceback
149
150   def run_user_code(envdir):
151       source = raw_input(">>> ")
152       try:
153           exec source in envdir
154       except:
155           print "Exception in user code:"
156           print '-'*60
157           traceback.print_exc(file=sys.stdout)
158           print '-'*60
159
160   envdir = {}
161   while 1:
162       run_user_code(envdir)
163
164
165The following example demonstrates the different ways to print and format the
166exception and traceback::
167
168   import sys, traceback
169
170   def lumberjack():
171       bright_side_of_death()
172
173   def bright_side_of_death():
174       return tuple()[0]
175
176   try:
177       lumberjack()
178   except:
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,
193                                             exceptionTraceback))
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)
199
200
201The output for the example would look similar to this::
202
203   *** print_tb:
204     File "<doctest...>", line 10, in <module>
205       lumberjack()
206   *** print_exception:
207   Traceback (most recent call last):
208     File "<doctest...>", line 10, in <module>
209       lumberjack()
210     File "<doctest...>", line 4, in lumberjack
211       bright_side_of_death()
212   IndexError: tuple index out of range
213   *** print_exc:
214   Traceback (most recent call last):
215     File "<doctest...>", line 10, in <module>
216       lumberjack()
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']
229   *** extract_tb:
230   [('<doctest...>', 10, '<module>', 'lumberjack()'),
231    ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
232    ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
233   *** format_tb:
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']
237   *** tb_lineno: 10
238
239
240The following example shows the different ways to print and format the stack::
241
242   >>> import traceback
243   >>> def another_function():
244   ...     lumberstack()
245   ...
246   >>> def lumberstack():
247   ...     traceback.print_stack()
248   ...     print repr(traceback.extract_stack())
249   ...     print repr(traceback.format_stack())
250   ...
251   >>> another_function()
252     File "<doctest>", line 10, in <module>
253       another_function()
254     File "<doctest>", line 3, in another_function
255       lumberstack()
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']
264
265
266This last example demonstrates the final few formatting functions:
267
268.. doctest::
269   :options: +NORMALIZE_WHITESPACE
270
271   >>> import traceback
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']