\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 printstack traces of Python programs.  It exactly mimics the behavior ofthe Python interpreter when it prints a stack trace.  This is usefulwhen you want to print stack traces under program control, such as in a``wrapper'' around the interpreter. The module uses traceback objects --- this is the object type that isstored in the variables \code{sys.exc_traceback} (deprecated) 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-likeobject 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 entriesfrom \var{traceback} to \var{file}.This differs from \function{print_tb()} in thefollowing ways: (1) if \var{traceback} is not \code{None}, it prints aheader \samp{Traceback (most recent call last):}; (2) it prints theexception \var{type} and \var{value} after the stack trace; (3) if\var{type} is \exception{SyntaxError} and \var{value} has theappropriate format, it prints the line where the syntax error occurredwith 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,sys.exc_value, sys.exc_traceback, \var{limit}, \var{file})}.  (Infact, it uses \function{sys.exc_info()} to retrieve the sameinformation in a thread-safe way instead of using the deprecatedvariables.)\end{funcdesc} \begin{funcdesc}{format_exc}{\optional{limit}}This is like \code{print_exc(\var{limit})} but returns a stringinstead of printing to a file.\versionadded{2.4}\end{funcdesc} \begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}This is a shorthand for \code{print_exception(sys.last_type,sys.last_value, sys.last_traceback, \var{limit}, \var{file})}.\end{funcdesc} \begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}This function prints a stack trace from its invocation point.  Theoptional \var{f} argument can be used to specify an alternate stackframe to start.  The optional \var{limit} and \var{file} arguments have thesame 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 traceentries extracted from the traceback object \var{traceback}.  It isuseful for alternate formatting of stack traces.  If \var{limit} isomitted 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}) representingthe information that is usually printed for a stack trace.  The\var{text} is a string with leading and trailing whitespacestripped; 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 returnvalue has the same format as for \function{extract_tb()}.  Theoptional \var{f} and \var{limit} arguments have the same meaning asfor \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 forprinting.  Each string in the resulting list corresponds to the itemwith the same index in the argument list.  Each string ends in anewline; the strings may contain internal newlines as well, for thoseitems 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 theexception type and value such as given by \code{sys.last_type} and\code{sys.last_value}.  The return value is a list of strings, eachending in a newline.  Normally, the list contains a single string;however, for \exception{SyntaxError} exceptions, it contains severallines that (when printed) display detailed information about where thesyntax error occurred.  The message indicating which exceptionoccurred 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.  Whenthese lines are concatenated and printed, exactly the same text isprinted 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 tracebackobject.  This function was necessary because in versions of Pythonprior to 2.3 when the \programopt{-O} flag was passed to Python the\code{\var{tb}.tb_lineno} was not updated correctly.  This functionhas no use in versions past 2.3.\end{funcdesc}  \subsection{Traceback Example \label{traceback-example}} This simple example implements a basic read-eval-print loop, similarto (but less useful than) the standard Python interactive interpreterloop.  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}