GNU Info

(python2.1-lib.info)traceback

---

Next: linecache Prev: inspect Up: Python Runtime Services

---

Enter node , (file) or (file)node

Print or retrieve a stack traceback
===================================

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, e.g. in a
"wrapper" around the interpreter.

The module uses traceback objects -- this is the object type that is
stored in the variables `sys.exc_traceback' and `sys.last_traceback'
and returned as the third item from `sys.exc_info()'.

The module defines the following functions:

`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.

`print_exception(type, value, traceback[, limit[, file]])'
     Print exception information and up to LIMIT stack trace entries
     from TRACEBACK to FILE.  This differs from `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 `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.

`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 `sys.exc_info()' to retrieve the same information in
     a thread-safe way.)

`print_last([limit[, file]])'
     This is a shorthand for ``print_exception(sys.last_type,'
     `sys.last_value,' `sys.last_traceback,' LIMIT`,' FILE`)''.

`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 `print_exception()'.

`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'.

`extract_stack([f[, limit]])'
     Extract the raw traceback from the current stack frame.  The return
     value has the same format as for `extract_tb()'.  The optional F
     and LIMIT arguments have the same meaning as for `print_stack()'.

`format_list(list)'
     Given a list of tuples as returned by `extract_tb()' or
     `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'.

`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 `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.

`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
     `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 `print_exception()'.

`format_tb(tb[, limit])'
     A shorthand for `format_list(extract_tb(TB, LIMIT))'.

`format_stack([f[, limit]])'
     A shorthand for `format_list(extract_stack(F, LIMIT))'.

`tb_lineno(tb)'
     This function returns the current line number set in the traceback
     object.  This is normally the same as the `TB.tb_lineno' field of
     the object, but when optimization is used (the -O flag) this field
     is not updated correctly; this function calculates the correct
     value.

Traceback Example