\section{\module{traceback} ---
         Print or retrieve a stack traceback.}
\declaremodule{standard}{traceback}

\modulesynopsis{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 \code{sys.exc_traceback} and
\code{sys.last_traceback} and returned as the third item from
\function{sys.exc_info()}.
\obindex{traceback}

The module defines the following functions:

\begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}}
Print up to \var{limit} stack trace entries from \var{traceback}.  If
\var{limit} is omitted or \code{None}, all entries are printed.
If \var{file} is omitted or \code{None}, the output goes to
\code{sys.stderr}; otherwise it should be an open file or file-like
object to receive the output.
\end{funcdesc}

\begin{funcdesc}{extract_tb}{traceback\optional{, limit}}
Return a list of up to \var{limit} ``pre-processed'' stack trace
entries extracted from \var{traceback}.  It is useful for alternate
formatting of stack traces.  If \var{limit} is omitted or \code{None},
all entries are extracted.  A ``pre-processed'' stack trace entry is a
quadruple (\var{filename}, \var{line number}, \var{function name},
\var{line text}) representing the information that is usually printed
for a stack trace.  The \var{line text} is a string with leading and
trailing whitespace stripped; if the source is not available it is
\code{None}.
\end{funcdesc}

\begin{funcdesc}{print_exception}{type, value,
traceback\optional{, limit\optional{, file}}}
Print exception information and up to \var{limit} stack trace entries
from \var{traceback} to \var{file}.
This differs from \function{print_tb()} in the
following ways: (1) if \var{traceback} is not \code{None}, it prints a
header \samp{Traceback (innermost last):}; (2) it prints the
exception \var{type} and \var{value} after the stack trace; (3) if
\var{type} is \exception{SyntaxError} and \var{value} has the appropriate
format, it prints the line where the syntax error occurred with a
caret indicating the approximate position of the error.
\end{funcdesc}

\begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}}
This is a shorthand for `\code{print_exception(sys.exc_type,}
\code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{,}
\var{file}\code{)}'.  (In fact, it uses \code{sys.exc_info()} to
retrieve the same information in a thread-safe way.)
\end{funcdesc}

\begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}
This is a shorthand for `\code{print_exception(sys.last_type,}
\code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{,}
\var{file}\code{)}'.
\end{funcdesc}

\begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}
This function prints a stack trace from its invocation point.  The
optional \var{f} argument can be used to specify an alternate stack
frame to start.  The optional \var{limit} and \var{file} arguments have the
same meaning as for \function{print_exception()}.
\end{funcdesc}

\begin{funcdesc}{extract_tb}{tb\optional{, limit}}
Return a list containing the raw (unformatted) traceback information
extracted from the traceback object \var{tb}.  The optional
\var{limit} argument has the same meaning as for
\function{print_exception()}.  The items in the returned list are
4-tuples containing the following values: filename, line number,
function name, and source text line.  The source text line is stripped 
of leading and trailing whitespace; it is \code{None} when the source
text file is unavailable.
\end{funcdesc}

\begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}}
Extract the raw traceback from the current stack frame.  The return
value has the same format as for \function{extract_tb()}.  The
optional \var{f} and \var{limit} arguments have the same meaning as
for \function{print_stack()}.
\end{funcdesc}

\begin{funcdesc}{format_list}{list}
Given a list of tuples as returned by \function{extract_tb()} or
\function{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 \code{None}.
\end{funcdesc}

\begin{funcdesc}{format_exception_only}{type, value}
Format the exception part of a traceback.  The arguments are the
exception type and value such as given by \code{sys.last_type} and
\code{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 \code{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.
\end{funcdesc}

\begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}}
Format a stack trace and the exception information.  The arguments 
have the same meaning as the corresponding arguments to
\function{print_exception()}.  The return value is a list of strings,
each ending in a newline and some containing internal newlines.  When
these lines are contatenated and printed, exactly the same text is
printed as does \function{print_exception()}.
\end{funcdesc}

\begin{funcdesc}{format_tb}{tb\optional{, limit}}
A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}.
\end{funcdesc}

\begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}}
A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}.
\end{funcdesc}

\begin{funcdesc}{tb_lineno}{tb}
This function returns the current line number set in the traceback
object.  This is normally the same as the \code{\var{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.
\end{funcdesc}

A simple example follows:

\begin{verbatim}
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)
\end{verbatim}