From bca1207ac8f2faeb990f6fe6be1441358a394d50 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Wed, 17 Jun 1998 22:37:26 +0000 Subject: [PATCH] Documented that by default the output goes to stderr, and that a file keyword argument can be used to direct it somewhere else. Also documented all the other functions in this module, and even added a little example. # Haven't tested the latex for correctness -- all latex installations # appear broken. --- Doc/lib/libtraceback.tex | 123 +++++++++++++++++++++++++++++++++++---- 1 file changed, 111 insertions(+), 12 deletions(-) diff --git a/Doc/lib/libtraceback.tex b/Doc/lib/libtraceback.tex index f9aa74a09b3..1d847631dad 100644 --- a/Doc/lib/libtraceback.tex +++ b/Doc/lib/libtraceback.tex @@ -3,22 +3,26 @@ \stmodindex{traceback} -This module provides a standard interface to format and print stack -traces of Python programs. It exactly mimics the behavior of the -Python interpreter when it prints a stack trace. This is useful when -you want to print stack traces under program control, e.g. in a +This module provides a standard interface to extract, format and print +stack traces of Python programs. It exactly mimics the behavior of +the Python interpreter when it prints a stack trace. This is useful +when you want to print stack traces under program control, e.g. in a ``wrapper'' around the interpreter. The module uses traceback objects --- this is the object type that is stored in the variables \code{sys.exc_traceback} and -\code{sys.last_traceback}. +\code{sys.last_traceback} and returned as the third item from +\function{sys.exc_info()}. \obindex{traceback} The module defines the following functions: -\begin{funcdesc}{print_tb}{traceback\optional{, limit}} +\begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}} Print up to \var{limit} stack trace entries from \var{traceback}. If \var{limit} is omitted or \code{None}, all entries are printed. +If \var{file} is omitted or \code{None}, the output goes to +\code{sys.stderr}; otherwise it should be an open file or file-like +object to receive the output. \end{funcdesc} \begin{funcdesc}{extract_tb}{traceback\optional{, limit}} @@ -33,9 +37,11 @@ trailing whitespace stripped; if the source is not available it is \code{None}. \end{funcdesc} -\begin{funcdesc}{print_exception}{type, value, traceback\optional{, limit}} +\begin{funcdesc}{print_exception}{type, value, +traceback\optional{, limit\optional{, file}}} Print exception information and up to \var{limit} stack trace entries -from \var{traceback}. This differs from \function{print_tb()} in the +from \var{traceback} to \var{file}. +This differs from \function{print_tb()} in the following ways: (1) if \var{traceback} is not \code{None}, it prints a header \samp{Traceback (innermost last):}; (2) it prints the exception \var{type} and \var{value} after the stack trace; (3) if @@ -44,12 +50,105 @@ format, it prints the line where the syntax error occurred with a caret indicating the approximate position of the error. \end{funcdesc} -\begin{funcdesc}{print_exc}{\optional{limit}} +\begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}} This is a shorthand for `\code{print_exception(sys.exc_type,} -\code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{)}'. +\code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{,} +\var{file}\code{)}'. (In fact, it uses \code{sys.exc_info()} to +retrieve the same information in a thread-safe way.) \end{funcdesc} -\begin{funcdesc}{print_last}{\optional{limit}} +\begin{funcdesc}{print_last}{\optional{limit\optional{, file}}} This is a shorthand for `\code{print_exception(sys.last_type,} -\code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{)}'. +\code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{,} +\var{file}\code{)}'. \end{funcdesc} + +\begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}} +This function prints a stack trace from its invocation point. The +optional \var{f} argument can be used to specify an alternate stack +frame to start. The optional \var{limit} and \var{file} arguments have the +same meaning as for \function{print_exception()}. +\end{funcdesc} + +\begin{funcdesc}{extract_tb}{tb\optional{, limit}} +Return a list containing the raw (unformatted) traceback information +extracted from the traceback object \var{tb}. The optional +\var{limit} argument has the same meaning as for +\function{print_exception()}. The items in the returned list are +4-tuples containing the following values: filename, line number, +function name, and source text line. The source text line is stripped +of leading and trailing whitespace; it is \code{None} when the source +text file is unavailable. +\end{funcdesc} + +\begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}} +Extract the raw traceback from the current stack frame. The return +value has the same format as for \function{extract_tb()}. The +optional \var{f} and \var{limit} arguments have the same meaning as +for \function{print_stack()}. +\end{funcdesc} + +\begin{funcdesc}{format_list}{list} +Given a list of tuples as returned by \function{extract_tb()} or +\function{extract_stack()}, return a list of strings ready for +printing. Each string in the resulting list corresponds to the item +with the same index in the argument list. Each string ends in a +newline; the strings may contain internal newlines as well, for those +items whose source text line is not \code{None}. +\end{funcdesc} + +\begin{funcdesc}{format_exception_only}{type, value} +Format the exception part of a traceback. The arguments are the +exception type and value such as given by \code{sys.last_type} and +\code{sys.last_value}. The return value is a list of strings, each +ending in a newline. Normally, the list contains a single string; +however, for \code{SyntaxError} exceptions, it contains several lines +that (when printed) display detailed information about where the +syntax error occurred. The message indicating which exception +occurred is the always last string in the list. +\end{funcdesc} + +\begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}} +Format a stack trace and the exception information. The arguments +have the same meaning as the corresponding arguments to +\function{print_exception()}. The return value is a list of strings, +each ending in a newline and some containing internal newlines. When +these lines are contatenated and printed, exactly the same text is +printed as does \function{print_exception()}. +\end{funcdesc} + +\begin{funcdesc}{format_tb}{tb\optional{, limit}} +A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}. +\end{funcdesc} + +\begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}} +A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}. +\end{funcdesc} + +\begin{funcdesc}{tb_lineno}{tb} +This function returns the current line number set in the traceback +object. This is normally the same as the \code{\var{tb}.tb_lineno} +field of the object, but when optimization is used (the -O flag) this +field is not updated correctly; this function calculates the correct +value. +\end{funcdesc} + +A simple example follows: + +\begin{verbatim} +import sys, traceback + +def run_user_code(envdir): + source = raw_input(">>> ") + try: + exec source in envdir + except: + print "Exception in user code:" + print '-'*60 + traceback.print_exc(file=sys.stdout) + print '-'*60 + +envdir = {} +while 1: + run_user_code(envdir) +\end{verbatim}