/Doc/library/traceback.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 278 lines · 206 code · 72 blank · 0 comment · 0 complexity · 528848f531dc022da80b5bfd85c803a1 MD5 · raw file
- :mod:`traceback` --- Print or retrieve a stack traceback
- ========================================================
- .. module:: traceback
- :synopsis: Print or retrieve a stack traceback.
- This module provides a standard interface to extract, format and print stack
- traces of Python programs. It exactly mimics the behavior of the Python
- interpreter when it prints a stack trace. This is useful when you want to print
- stack traces under program control, such as in a "wrapper" around the
- interpreter.
- .. index:: object: traceback
- The module uses traceback objects --- this is the object type that is stored in
- the variables :data:`sys.exc_traceback` (deprecated) and :data:`sys.last_traceback` and
- returned as the third item from :func:`sys.exc_info`.
- The module defines the following functions:
- .. function:: print_tb(traceback[, limit[, file]])
- Print up to *limit* stack trace entries from *traceback*. If *limit* is omitted
- or ``None``, all entries are printed. If *file* is omitted or ``None``, the
- output goes to ``sys.stderr``; otherwise it should be an open file or file-like
- object to receive the output.
- .. function:: print_exception(type, value, traceback[, limit[, file]])
- Print exception information and up to *limit* stack trace entries from
- *traceback* to *file*. This differs from :func:`print_tb` in the following ways:
- (1) if *traceback* is not ``None``, it prints a header ``Traceback (most recent
- call last):``; (2) it prints the exception *type* and *value* after the stack
- trace; (3) if *type* is :exc:`SyntaxError` and *value* has the appropriate
- format, it prints the line where the syntax error occurred with a caret
- indicating the approximate position of the error.
- .. function:: print_exc([limit[, file]])
- This is a shorthand for ``print_exception(sys.exc_type, sys.exc_value,
- sys.exc_traceback, limit, file)``. (In fact, it uses :func:`sys.exc_info` to
- retrieve the same information in a thread-safe way instead of using the
- deprecated variables.)
- .. function:: format_exc([limit])
- This is like ``print_exc(limit)`` but returns a string instead of printing to a
- file.
- .. versionadded:: 2.4
- .. function:: print_last([limit[, file]])
- This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
- sys.last_traceback, limit, file)``. In general it will work only after
- an exception has reached an interactive prompt (see :data:`sys.last_type`).
- .. function:: print_stack([f[, limit[, file]]])
- This function prints a stack trace from its invocation point. The optional *f*
- argument can be used to specify an alternate stack frame to start. The optional
- *limit* and *file* arguments have the same meaning as for
- :func:`print_exception`.
- .. function:: extract_tb(traceback[, limit])
- Return a list of up to *limit* "pre-processed" stack trace entries extracted
- from the traceback object *traceback*. It is useful for alternate formatting of
- stack traces. If *limit* is omitted or ``None``, all entries are extracted. A
- "pre-processed" stack trace entry is a quadruple (*filename*, *line number*,
- *function name*, *text*) representing the information that is usually printed
- for a stack trace. The *text* is a string with leading and trailing whitespace
- stripped; if the source is not available it is ``None``.
- .. function:: extract_stack([f[, limit]])
- Extract the raw traceback from the current stack frame. The return value has
- the same format as for :func:`extract_tb`. The optional *f* and *limit*
- arguments have the same meaning as for :func:`print_stack`.
- .. function:: format_list(list)
- Given a list of tuples as returned by :func:`extract_tb` or
- :func:`extract_stack`, return a list of strings ready for printing. Each string
- in the resulting list corresponds to the item with the same index in the
- argument list. Each string ends in a newline; the strings may contain internal
- newlines as well, for those items whose source text line is not ``None``.
- .. function:: format_exception_only(type, value)
- Format the exception part of a traceback. The arguments are the exception type
- and value such as given by ``sys.last_type`` and ``sys.last_value``. The return
- value is a list of strings, each ending in a newline. Normally, the list
- contains a single string; however, for :exc:`SyntaxError` exceptions, it
- contains several lines that (when printed) display detailed information about
- where the syntax error occurred. The message indicating which exception
- occurred is the always last string in the list.
- .. function:: format_exception(type, value, tb[, limit])
- Format a stack trace and the exception information. The arguments have the
- same meaning as the corresponding arguments to :func:`print_exception`. The
- return value is a list of strings, each ending in a newline and some containing
- internal newlines. When these lines are concatenated and printed, exactly the
- same text is printed as does :func:`print_exception`.
- .. function:: format_tb(tb[, limit])
- A shorthand for ``format_list(extract_tb(tb, limit))``.
- .. function:: format_stack([f[, limit]])
- A shorthand for ``format_list(extract_stack(f, limit))``.
- .. function:: tb_lineno(tb)
- This function returns the current line number set in the traceback object. This
- function was necessary because in versions of Python prior to 2.3 when the
- :option:`-O` flag was passed to Python the ``tb.tb_lineno`` was not updated
- correctly. This function has no use in versions past 2.3.
- .. _traceback-example:
- Traceback Examples
- ------------------
- This simple example implements a basic read-eval-print loop, similar to (but
- less useful than) the standard Python interactive interpreter loop. For a more
- complete implementation of the interpreter loop, refer to the :mod:`code`
- module. ::
- import sys, traceback
- def run_user_code(envdir):
- source = raw_input(">>> ")
- try:
- exec source in envdir
- except:
- print "Exception in user code:"
- print '-'*60
- traceback.print_exc(file=sys.stdout)
- print '-'*60
- envdir = {}
- while 1:
- run_user_code(envdir)
- The following example demonstrates the different ways to print and format the
- exception and traceback::
- import sys, traceback
- def lumberjack():
- bright_side_of_death()
- def bright_side_of_death():
- return tuple()[0]
- try:
- lumberjack()
- except:
- exceptionType, exceptionValue, exceptionTraceback = sys.exc_info()
- print "*** print_tb:"
- traceback.print_tb(exceptionTraceback, limit=1, file=sys.stdout)
- print "*** print_exception:"
- traceback.print_exception(exceptionType, exceptionValue, exceptionTraceback,
- limit=2, file=sys.stdout)
- print "*** print_exc:"
- traceback.print_exc()
- print "*** format_exc, first and last line:"
- formatted_lines = traceback.format_exc().splitlines()
- print formatted_lines[0]
- print formatted_lines[-1]
- print "*** format_exception:"
- print repr(traceback.format_exception(exceptionType, exceptionValue,
- exceptionTraceback))
- print "*** extract_tb:"
- print repr(traceback.extract_tb(exceptionTraceback))
- print "*** format_tb:"
- print repr(traceback.format_tb(exceptionTraceback))
- print "*** tb_lineno:", traceback.tb_lineno(exceptionTraceback)
- The output for the example would look similar to this::
- *** print_tb:
- File "<doctest...>", line 10, in <module>
- lumberjack()
- *** print_exception:
- Traceback (most recent call last):
- File "<doctest...>", line 10, in <module>
- lumberjack()
- File "<doctest...>", line 4, in lumberjack
- bright_side_of_death()
- IndexError: tuple index out of range
- *** print_exc:
- Traceback (most recent call last):
- File "<doctest...>", line 10, in <module>
- lumberjack()
- File "<doctest...>", line 4, in lumberjack
- bright_side_of_death()
- IndexError: tuple index out of range
- *** format_exc, first and last line:
- Traceback (most recent call last):
- IndexError: tuple index out of range
- *** format_exception:
- ['Traceback (most recent call last):\n',
- ' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
- ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
- ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n',
- 'IndexError: tuple index out of range\n']
- *** extract_tb:
- [('<doctest...>', 10, '<module>', 'lumberjack()'),
- ('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
- ('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
- *** format_tb:
- [' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
- ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
- ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n']
- *** tb_lineno: 10
- The following example shows the different ways to print and format the stack::
- >>> import traceback
- >>> def another_function():
- ... lumberstack()
- ...
- >>> def lumberstack():
- ... traceback.print_stack()
- ... print repr(traceback.extract_stack())
- ... print repr(traceback.format_stack())
- ...
- >>> another_function()
- File "<doctest>", line 10, in <module>
- another_function()
- File "<doctest>", line 3, in another_function
- lumberstack()
- File "<doctest>", line 6, in lumberstack
- traceback.print_stack()
- [('<doctest>', 10, '<module>', 'another_function()'),
- ('<doctest>', 3, 'another_function', 'lumberstack()'),
- ('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')]
- [' File "<doctest>", line 10, in <module>\n another_function()\n',
- ' File "<doctest>", line 3, in another_function\n lumberstack()\n',
- ' File "<doctest>", line 8, in lumberstack\n print repr(traceback.format_stack())\n']
- This last example demonstrates the final few formatting functions:
- .. doctest::
- :options: +NORMALIZE_WHITESPACE
- >>> import traceback
- >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
- ... ('eggs.py', 42, 'eggs', 'return "bacon"')])
- [' File "spam.py", line 3, in <module>\n spam.eggs()\n',
- ' File "eggs.py", line 42, in eggs\n return "bacon"\n']
- >>> an_error = IndexError('tuple index out of range')
- >>> traceback.format_exception_only(type(an_error), an_error)
- ['IndexError: tuple index out of range\n']