Doc/lib/libtraceback.tex

   1 \section{\module{traceback} ---
   2          Print or retrieve a stack traceback}
   3
   4 \declaremodule{standard}{traceback}
   5 \modulesynopsis{Print or retrieve a stack traceback.}
   6
   7
   8 This module provides a standard interface to extract, format and print
   9 stack traces of Python programs.  It exactly mimics the behavior of
  10 the Python interpreter when it prints a stack trace.  This is useful
  11 when you want to print stack traces under program control, e.g. in a
  12 ``wrapper'' around the interpreter.
  13
  14 The module uses traceback objects --- this is the object type
  15 that is stored in the variables \code{sys.exc_traceback} and
  16 \code{sys.last_traceback} and returned as the third item from
  17 \function{sys.exc_info()}.
  18 \obindex{traceback}
  19
  20 The module defines the following functions:
  21
  22 \begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}}
  23 Print up to \var{limit} stack trace entries from \var{traceback}.  If
  24 \var{limit} is omitted or \code{None}, all entries are printed.
  25 If \var{file} is omitted or \code{None}, the output goes to
  26 \code{sys.stderr}; otherwise it should be an open file or file-like
  27 object to receive the output.
  28 \end{funcdesc}
  29
  30 \begin{funcdesc}{print_exception}{type, value, traceback\optional{,
  31                                   limit\optional{, file}}}
  32 Print exception information and up to \var{limit} stack trace entries
  33 from \var{traceback} to \var{file}.
  34 This differs from \function{print_tb()} in the
  35 following ways: (1) if \var{traceback} is not \code{None}, it prints a
  36 header \samp{Traceback (innermost last):}; (2) it prints the
  37 exception \var{type} and \var{value} after the stack trace; (3) if
  38 \var{type} is \exception{SyntaxError} and \var{value} has the appropriate
  39 format, it prints the line where the syntax error occurred with a
  40 caret indicating the approximate position of the error.
  41 \end{funcdesc}
  42
  43 \begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}}
  44 This is a shorthand for `\code{print_exception(sys.exc_type,}
  45 \code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{,}
  46 \var{file}\code{)}'.  (In fact, it uses \code{sys.exc_info()} to
  47 retrieve the same information in a thread-safe way.)
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}
  51 This is a shorthand for `\code{print_exception(sys.last_type,}
  52 \code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{,}
  53 \var{file}\code{)}'.
  54 \end{funcdesc}
  55
  56 \begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}
  57 This function prints a stack trace from its invocation point.  The
  58 optional \var{f} argument can be used to specify an alternate stack
  59 frame to start.  The optional \var{limit} and \var{file} arguments have the
  60 same meaning as for \function{print_exception()}.
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{extract_tb}{traceback\optional{, limit}}
  64 Return a list of up to \var{limit} ``pre-processed'' stack trace
  65 entries extracted from the traceback object \var{traceback}.  It is
  66 useful for alternate formatting of stack traces.  If \var{limit} is
  67 omitted or \code{None}, all entries are extracted.  A
  68 ``pre-processed'' stack trace entry is a quadruple (\var{filename},
  69 \var{line number}, \var{function name}, \var{text}) representing
  70 the information that is usually printed for a stack trace.  The
  71 \var{text} is a string with leading and trailing whitespace
  72 stripped; if the source is not available it is \code{None}.
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}}
  76 Extract the raw traceback from the current stack frame.  The return
  77 value has the same format as for \function{extract_tb()}.  The
  78 optional \var{f} and \var{limit} arguments have the same meaning as
  79 for \function{print_stack()}.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{format_list}{list}
  83 Given a list of tuples as returned by \function{extract_tb()} or
  84 \function{extract_stack()}, return a list of strings ready for
  85 printing.  Each string in the resulting list corresponds to the item
  86 with the same index in the argument list.  Each string ends in a
  87 newline; the strings may contain internal newlines as well, for those
  88 items whose source text line is not \code{None}.
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{format_exception_only}{type, value}
  92 Format the exception part of a traceback.  The arguments are the
  93 exception type and value such as given by \code{sys.last_type} and
  94 \code{sys.last_value}.  The return value is a list of strings, each
  95 ending in a newline.  Normally, the list contains a single string;
  96 however, for \code{SyntaxError} exceptions, it contains several lines
  97 that (when printed) display detailed information about where the
  98 syntax error occurred.  The message indicating which exception
  99 occurred is the always last string in the list.
 100 \end{funcdesc}
 101
 102 \begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}}
 103 Format a stack trace and the exception information.  The arguments
 104 have the same meaning as the corresponding arguments to
 105 \function{print_exception()}.  The return value is a list of strings,
 106 each ending in a newline and some containing internal newlines.  When
 107 these lines are contatenated and printed, exactly the same text is
 108 printed as does \function{print_exception()}.
 109 \end{funcdesc}
 110
 111 \begin{funcdesc}{format_tb}{tb\optional{, limit}}
 112 A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}.
 113 \end{funcdesc}
 114
 115 \begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}}
 116 A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}.
 117 \end{funcdesc}
 118
 119 \begin{funcdesc}{tb_lineno}{tb}
 120 This function returns the current line number set in the traceback
 121 object.  This is normally the same as the \code{\var{tb}.tb_lineno}
 122 field of the object, but when optimization is used (the -O flag) this
 123 field is not updated correctly; this function calculates the correct
 124 value.
 125 \end{funcdesc}
 126
 127
 128 \subsection{Traceback Example \label{traceback-example}}
 129
 130 This simple example implements a basic read-eval-print loop, similar
 131 to (but less useful than) the standard Python interactive interpreter
 132 loop.  For a more complete implementation of the interpreter loop,
 133 refer to the \refmodule{code} module.
 134
 135 \begin{verbatim}
 136 import sys, traceback
 137
 138 def run_user_code(envdir):
 139     source = raw_input(">>> ")
 140     try:
 141         exec source in envdir
 142     except:
 143         print "Exception in user code:"
 144         print '-'*60
 145         traceback.print_exc(file=sys.stdout)
 146         print '-'*60
 147
 148 envdir = {}
 149 while 1:
 150     run_user_code(envdir)
 151 \end{verbatim}