Doc/lib/libtraceback.tex

   1 \section{Standard Module \sectcode{traceback}}
   2 \stmodindex{traceback}
   3
   4 \renewcommand{\indexsubitem}{(in module traceback)}
   5
   6 This module provides a standard interface to format and print stack
   7 traces of Python programs.  It exactly mimics the behavior of the
   8 Python interpreter when it prints a stack trace.  This is useful when
   9 you want to print stack traces under program control, e.g. in a
  10 ``wrapper'' around the interpreter.
  11
  12 The module uses traceback objects --- this is the object type
  13 that is stored in the variables \code{sys.exc_traceback} and
  14 \code{sys.last_traceback}.
  15
  16 The module defines the following functions:
  17
  18 \begin{funcdesc}{print_tb}{traceback\optional{\, limit}}
  19 Print up to \var{limit} stack trace entries from \var{traceback}.  If
  20 \var{limit} is omitted or \code{None}, all entries are printed.
  21 \end{funcdesc}
  22
  23 \begin{funcdesc}{extract_tb}{traceback\optional{\, limit}}
  24 Return a list of up to \var{limit} ``pre-processed'' stack trace
  25 entries extracted from \var{traceback}.  It is useful for alternate
  26 formatting of stack traces.  If \var{limit} is omitted or \code{None},
  27 all entries are extracted.  A ``pre-processed'' stack trace entry is a
  28 quadruple (\var{filename}, \var{line number}, \var{function name},
  29 \var{line text}) representing the information that is usually printed
  30 for a stack trace.  The \var{line text} is a string with leading and
  31 trailing whitespace stripped; if the source is not available it is
  32 \code{None}.
  33 \end{funcdesc}
  34
  35 \begin{funcdesc}{print_exception}{type\, value\, traceback\optional{\, limit}}
  36 Print exception information and up to \var{limit} stack trace entries
  37 from \var{traceback}.  This differs from \code{print_tb} in the
  38 following ways: (1) if \var{traceback} is not \code{None}, it prints a
  39 header ``\code{Traceback (innermost last):}''; (2) it prints the
  40 exception \var{type} and \var{value} after the stack trace; (3) if
  41 \var{type} is \code{SyntaxError} and \var{value} has the appropriate
  42 format, it prints the line where the syntax error occurred with a
  43 caret indication the approximate position of the error.
  44 \end{funcdesc}
  45
  46 \begin{funcdesc}{print_exc}{\optional{limit}}
  47 This is a shorthand for \code{print_exception(sys.exc_type,}
  48 \code{sys.exc_value,} \code{sys.exc_traceback,} \code{limit)}.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{print_last}{\optional{limit}}
  52 This is a shorthand for \code{print_exception(sys.last_type,}
  53 \code{sys.last_value,} \code{sys.last_traceback,} \code{limit)}.
  54 \end{funcdesc}