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.
diff --git a/Doc/lib/libtraceback.tex b/Doc/lib/libtraceback.tex
index f9aa74a..1d84763 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 @@
\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 @@
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}