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, such as in a
  12 ``wrapper'' around the interpreter.
  13
  14 The module uses traceback objects --- this is the object type that is
  15 stored in the variables \code{sys.exc_traceback} (deprecated) 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 (most recent call 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
  39 appropriate format, it prints the line where the syntax error occurred
  40 with a 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 sys.exc_value, sys.exc_traceback, \var{limit}, \var{file})}.  (In
  46 fact, it uses \function{sys.exc_info()} to retrieve the same
  47 information in a thread-safe way instead of using the deprecated
  48 variables.)
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{format_exc}{\optional{limit}}
  52 This is like \code{print_exc(\var{limit})} but returns a string
  53 instead of printing to a file.
  54 \versionadded{2.4}
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}
  58 This is a shorthand for \code{print_exception(sys.last_type,
  59 sys.last_value, sys.last_traceback, \var{limit}, \var{file})}.
  60 \end{funcdesc}
  61
  62 \begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}
  63 This function prints a stack trace from its invocation point.  The
  64 optional \var{f} argument can be used to specify an alternate stack
  65 frame to start.  The optional \var{limit} and \var{file} arguments have the
  66 same meaning as for \function{print_exception()}.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{extract_tb}{traceback\optional{, limit}}
  70 Return a list of up to \var{limit} ``pre-processed'' stack trace
  71 entries extracted from the traceback object \var{traceback}.  It is
  72 useful for alternate formatting of stack traces.  If \var{limit} is
  73 omitted or \code{None}, all entries are extracted.  A
  74 ``pre-processed'' stack trace entry is a quadruple (\var{filename},
  75 \var{line number}, \var{function name}, \var{text}) representing
  76 the information that is usually printed for a stack trace.  The
  77 \var{text} is a string with leading and trailing whitespace
  78 stripped; if the source is not available it is \code{None}.
  79 \end{funcdesc}
  80
  81 \begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}}
  82 Extract the raw traceback from the current stack frame.  The return
  83 value has the same format as for \function{extract_tb()}.  The
  84 optional \var{f} and \var{limit} arguments have the same meaning as
  85 for \function{print_stack()}.
  86 \end{funcdesc}
  87
  88 \begin{funcdesc}{format_list}{list}
  89 Given a list of tuples as returned by \function{extract_tb()} or
  90 \function{extract_stack()}, return a list of strings ready for
  91 printing.  Each string in the resulting list corresponds to the item
  92 with the same index in the argument list.  Each string ends in a
  93 newline; the strings may contain internal newlines as well, for those
  94 items whose source text line is not \code{None}.
  95 \end{funcdesc}
  96
  97 \begin{funcdesc}{format_exception_only}{type, value}
  98 Format the exception part of a traceback.  The arguments are the
  99 exception type and value such as given by \code{sys.last_type} and
 100 \code{sys.last_value}.  The return value is a list of strings, each
 101 ending in a newline.  Normally, the list contains a single string;
 102 however, for \exception{SyntaxError} exceptions, it contains several
 103 lines that (when printed) display detailed information about where the
 104 syntax error occurred.  The message indicating which exception
 105 occurred is the always last string in the list.
 106 \end{funcdesc}
 107
 108 \begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}}
 109 Format a stack trace and the exception information.  The arguments
 110 have the same meaning as the corresponding arguments to
 111 \function{print_exception()}.  The return value is a list of strings,
 112 each ending in a newline and some containing internal newlines.  When
 113 these lines are concatenated and printed, exactly the same text is
 114 printed as does \function{print_exception()}.
 115 \end{funcdesc}
 116
 117 \begin{funcdesc}{format_tb}{tb\optional{, limit}}
 118 A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}.
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}}
 122 A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}.
 123 \end{funcdesc}
 124
 125 \begin{funcdesc}{tb_lineno}{tb}
 126 This function returns the current line number set in the traceback
 127 object.  This function was necessary because in versions of Python
 128 prior to 2.3 when the \programopt{-O} flag was passed to Python the
 129 \code{\var{tb}.tb_lineno} was not updated correctly.  This function
 130 has no use in versions past 2.3.
 131 \end{funcdesc}
 132
 133
 134 \subsection{Traceback Example \label{traceback-example}}
 135
 136 This simple example implements a basic read-eval-print loop, similar
 137 to (but less useful than) the standard Python interactive interpreter
 138 loop.  For a more complete implementation of the interpreter loop,
 139 refer to the \refmodule{code} module.
 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}