Doc/lib/libtraceback.tex

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