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