l4/pkg/python/contrib/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
   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
  12 interpreter.
  13
  14 .. index:: object: traceback
  15
  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`.
  19
  20 The 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
 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
 200
 201 The 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
 240 The 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
 266 This 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']