152 lines
6.3 KiB
TeX
152 lines
6.3 KiB
TeX
\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}{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}{traceback\optional{, limit}}
|
|
Return a list of up to \var{limit} ``pre-processed'' stack trace
|
|
entries extracted from the traceback object \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{text}) representing
|
|
the information that is usually printed for a stack trace. The
|
|
\var{text} is a string with leading and trailing whitespace
|
|
stripped; if the source is not available it is \code{None}.
|
|
\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}
|
|
|
|
|
|
\subsection{Traceback Example \label{traceback-example}}
|
|
|
|
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 \refmodule{code} module.
|
|
|
|
\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}
|