Doc/library/traceback.rst

   1
   2 :mod:`traceback` --- Print or retrieve a stack traceback
   3 ========================================================
   4
   5 .. module:: traceback
   6    :synopsis: Print or retrieve a stack traceback.
   7
   8
   9 This module provides a standard interface to extract, format and print stack
  10 traces of Python programs.  It exactly mimics the behavior of the Python
  11 interpreter when it prints a stack trace.  This is useful when you want to print
  12 stack traces under program control, such as in a "wrapper" around the
  13 interpreter.
  14
  15 .. index:: object: traceback
  16
  17 The module uses traceback objects --- this is the object type that is stored in
  18 the variables ``sys.exc_traceback`` (deprecated) and ``sys.last_traceback`` and
  19 returned as the third item from :func:`sys.exc_info`.
  20
  21 The module defines the following functions:
  22
  23
  24 .. function:: print_tb(traceback[, limit[, file]])
  25
  26    Print up to *limit* stack trace entries from *traceback*.  If *limit* is omitted
  27    or ``None``, all entries are printed. If *file* is omitted or ``None``, the
  28    output goes to ``sys.stderr``; otherwise it should be an open file or file-like
  29    object to receive the output.
  30
  31
  32 .. function:: print_exception(type, value, traceback[, limit[, file]])
  33
  34    Print exception information and up to *limit* stack trace entries from
  35    *traceback* to *file*. This differs from :func:`print_tb` in the following ways:
  36    (1) if *traceback* is not ``None``, it prints a header ``Traceback (most recent
  37    call last):``; (2) it prints the exception *type* and *value* after the stack
  38    trace; (3) if *type* is :exc:`SyntaxError` and *value* has the appropriate
  39    format, it prints the line where the syntax error occurred with a caret
  40    indicating the approximate position of the error.
  41
  42
  43 .. function:: print_exc([limit[, file]])
  44
  45    This is a shorthand for ``print_exception(sys.exc_type, sys.exc_value,
  46    sys.exc_traceback, limit, file)``.  (In fact, it uses :func:`sys.exc_info` to
  47    retrieve the same information in a thread-safe way instead of using the
  48    deprecated variables.)
  49
  50
  51 .. function:: format_exc([limit])
  52
  53    This is like ``print_exc(limit)`` but returns a string instead of printing to a
  54    file.
  55
  56    .. versionadded:: 2.4
  57
  58
  59 .. function:: print_last([limit[, file]])
  60
  61    This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
  62    sys.last_traceback, limit, file)``.
  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
 140 Traceback Examples
 141 ------------------
 142
 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`
 146 module. ::
 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
 165 The following example demonstrates the different ways to print and format the
 166 exception 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    print "*** print_last:"
 200    traceback.print_last()
 201
 202
 203 The output for the example would look similar to this::
 204
 205    *** print_tb:
 206      File "<doctest>", line 9, in <module>
 207        lumberjack()
 208    *** print_exception:
 209    Traceback (most recent call last):
 210      File "<doctest>", line 9, in <module>
 211        lumberjack()
 212      File "<doctest>", line 3, in lumberjack
 213        bright_side_of_death()
 214    IndexError: tuple index out of range
 215    *** print_exc:
 216    Traceback (most recent call last):
 217      File "<doctest>", line 9, in <module>
 218        lumberjack()
 219      File "<doctest>", line 3, in lumberjack
 220        bright_side_of_death()
 221    IndexError: tuple index out of range
 222    *** format_exc, first and last line:
 223    Traceback (most recent call last):
 224    IndexError: tuple index out of range
 225    *** format_exception:
 226    ['Traceback (most recent call last):\n',
 227     '  File "<doctest>", line 9, in <module>\n    lumberjack()\n',
 228     '  File "<doctest>", line 3, in lumberjack\n    bright_side_of_death()\n',
 229     '  File "<doctest>", line 6, in bright_side_of_death\n    return tuple()[0]\n',
 230     'IndexError: tuple index out of range\n']
 231    *** extract_tb:
 232    [('<doctest>', 9, '<module>', 'lumberjack()'),
 233     ('<doctest>', 3, 'lumberjack', 'bright_side_of_death()'),
 234     ('<doctest>', 6, 'bright_side_of_death', 'return tuple()[0]')]
 235    *** format_tb:
 236    ['  File "<doctest>", line 9, in <module>\n    lumberjack()\n',
 237     '  File "<doctest>", line 3, in lumberjack\n    bright_side_of_death()\n',
 238     '  File "<doctest>", line 6, in bright_side_of_death\n    return tuple()[0]\n']
 239    *** tb_lineno: 2
 240    *** print_last:
 241    Traceback (most recent call last):
 242      File "<doctest>", line 9, in <module>
 243        lumberjack()
 244      File "<doctest>", line 3, in lumberjack
 245        bright_side_of_death()
 246    IndexError: tuple index out of range
 247
 248
 249 The following example shows the different ways to print and format the stack::
 250
 251    >>> import traceback
 252    >>> def another_function():
 253    ...     lumberstack()
 254    ...
 255    >>> def lumberstack():
 256    ...     traceback.print_stack()
 257    ...     print repr(traceback.extract_stack())
 258    ...     print repr(traceback.format_stack())
 259    ...
 260    >>> another_function()
 261      File "<doctest>", line 10, in <module>
 262        another_function()
 263      File "<doctest>", line 3, in another_function
 264        lumberstack()
 265      File "<doctest>", line 6, in lumberstack
 266        traceback.print_stack()
 267    [('<doctest>', 10, '<module>', 'another_function()'),
 268     ('<doctest>', 3, 'another_function', 'lumberstack()'),
 269     ('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')]
 270    ['  File "<doctest>", line 10, in <module>\n    another_function()\n',
 271     '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
 272     '  File "<doctest>", line 8, in lumberstack\n    print repr(traceback.format_stack())\n']
 273
 274
 275 This last example demonstrates the final few formatting functions::
 276
 277    >>> import traceback
 278    >>> format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
 279    ...              ('eggs.py', 42, 'eggs', 'return "bacon"')])
 280    ['  File "spam.py", line 3, in <module>\n    spam.eggs()\n',
 281     '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
 282    >>> theError = IndexError('tuple indx out of range')
 283    >>> traceback.format_exception_only(type(theError), theError)
 284    ['IndexError: tuple index out of range\n']