8000 Documented that by default the output goes to stderr, and that a file · python/cpython@bca1207 · GitHub
[go: up one dir, main page]
Skip to content

Commit bca1207

Browse files
gvanrossumgvanrossum
committed
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.
1 parent e50b0a4 commit bca1207

File tree

1 file changed

+111
-12
lines changed

1 file changed

+111
-12
lines changed

‎Doc/lib/libtraceback.tex

Lines changed: 111 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,26 @@ \section{Standard Module \module{traceback}}
33
\stmodindex{traceback}
44

55

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
6+
This module provides a standard interface to extract, format and print
7+
stack traces of Python programs. It exactly mimics the behavior of
8+
the Python interpreter when it prints a stack trace. This is useful
9+
when you want to print stack traces under program control, e.g. in a
1010
``wrapper'' around the interpreter.
1111

1212
The module uses traceback objects --- this is the object type
1313
that is stored in the variables \code{sys.exc_traceback} and
14-
\code{sys.last_traceback}.
14+
\code{sys.last_traceback} and returned as the third item from
15+
\function{sys.exc_info()}.
1516
\obindex{traceback}
1617

1718
The module defines the following functions:
1819

19-
\begin{funcdesc}{print_tb}{traceback\optional{, limit}}
20+
\begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}}
2021
Print up to \var{limit} stack trace entries from \var{traceback}. If
2122
\var{limit} is omitted or \code{None}, all entries are printed.
23+
If \var{file} is omitted or \code{None}, the output goes to
24+
\code{sys.stderr}; otherwise it should be an open file or file-like
25+
object to receive the output.
2226
\end{funcdesc}
2327

2428
\begin{funcdesc}{extract_tb}{traceback\optional{, limit}}
@@ -33,9 +37,11 @@ \section{Standard Module \module{traceback}}
3337
\code{None}.
3438
\end{funcdesc}
3539

36-
\begin{funcdesc}{print_exception}{type, value, traceback\optional{, limit}}
40+
\begin{funcdesc}{print_exception}{type, value,
41+
traceback\optional{, limit\optional{, file}}}
3742
Print exception information and up to \var{limit} stack trace entries
38-
from \var{traceback}. This differs from \function{print_tb()} in the
43+
from \var{traceback} to \var{file}.
44+
This differs from \function{print_tb()} in the
3945
following ways: (1) if \var{traceback} is not \code{None}, it prints a
4046
header \samp{Traceback (innermost last):}; (2) it prints the
4147
exception \var{type} and \var{value} after the stack trace; (3) if
@@ -44,12 +50,105 @@ \section{Standard Module \module{traceback}}
4450
caret indicating the approximate position of the error.
4551
\end{funcdesc}
4652

47-
\begin{funcdesc}{print_exc}{\optional{limit}}
53+
\begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}}
4854
This is a shorthand for `\code{print_exception(sys.exc_type,}
49-
\code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{)}'.
55+
\code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{,}
56+
\var{file}\code{)}'. (In fact, it uses \code{sys.exc_info()} to
57+
retrieve the same information in a thread-safe way.)
5058
\end{funcdesc}
5159

52-
\begin{funcdesc}{print_last}{\optional{limit}}
60+
\begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}
5361
This is a shorthand for `\code{print_exception(sys.last_type,}
54-
\code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{)}'.
62+
\code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{,}
63+
\var{file}\code{)}'.
5564
\end{funcdesc}
65+
66+
\begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}
67+
This function prints a stack trace from its invocation point. The
68+
optional \var{f} argument can be used to specify an alternate stack
69+
frame to start. The optional \var{limit} and \var{file} arguments have the
70+
same meaning as for \function{print_exception()}.
71+
\end{funcdesc}
72+
73+
\begin{funcdesc}{extract_tb}{tb\optional{, limit}}
74+
Return a list containing the raw (unformatted) traceback information
75+
extracted from the traceback object \var{tb}. The optional
76+
\var{limit} argument has the same meaning as for
77+
\function{print_exception()}. The items in the returned list are
78+
4-tuples containing the following values: filename, line number,
79+
function name, and source text line. The source text line is stripped
80+
of leading and trailing whitespace; it is \code{None} when the source
81+
text file is unavailable.
82+
\end{funcdesc}
83+
84+
\begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}}
85+
Extract the raw traceback from the current stack frame. The return
86+
value has the same format as for \function{extract_tb()}. The
87+
optional \var{f} and \var{limit} arguments have the same meaning as
88+
for \function{print_stack()}.
89+
\end{funcdesc}
90+
91+
\begin{funcdesc}{format_list}{list}
92+
Given a list of tuples as returned by \function{extract_tb()} or
93+
\function{extract_stack()}, return a list of strings ready for
94+
printing. Each string in the resulting list corresponds to the item
95+
with the same index in the argument list. Each string ends in a
96+
newline; the strings may contain internal newlines as well, for those
97+
items whose source text line is not \code{None}.
98+
\end{funcdesc}
99+
100+
\begin{funcdesc}{format_exception_only}{type, value}
101+
Format the exception part of a traceback. The arguments are the
102+
exception type and value such as given by \code{sys.last_type} and
103+
\code{sys.last_value}. The return value is a list of strings, each
104+
ending in a newline. Normally, the list contains a single string;
105+
however, for \code{SyntaxError} exceptions, it contains several lines
106+
that (when printed) display detailed information about where the
107+
syntax error occurred. The message indicating which exception
108+
occurred is the always last string in the list.
109+
\end{funcdesc}
110+
111+
\begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}}
112+
Format a stack trace and the exception information. The arguments
113+
have the same meaning as the corresponding arguments to
114+
\function{print_exception()}. The return value is a list of strings,
115+
each ending in a newline and some containing internal newlines. When
116+
these lines are contatenated and printed, exactly the same text is
117+
printed as does \function{print_exception()}.
118+
\end{funcdesc}
119+
120+
\begin{funcdesc}{format_tb}{tb\optional{, limit}}
121+
A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}.
122+
\end{funcdesc}
123+
124+
\begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}}
125+
A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}.
126+
\end{funcdesc}
127+
128+
\begin{funcdesc}{tb_lineno}{tb}
129+
This function returns the current line number set in the traceback
130+
object. This is normally the same as the \code{\var{tb}.tb_lineno}
131+
field of the object, but when optimization is used (the -O flag) this
132+
field is not updated correctly; this function calculates the correct
133+
value.
134+
\end{funcdesc}
135+
136+
A simple example follows:
137+
138+
\begin{verbatim}
139+
import sys, traceback
140+
141+
def run_user_code(envdir):
142+
source = raw_input(">>> ")
143+
try:
144+
exec source in envdir
145+
except:
146+
print "Exception in user code:"
147+
print '-'*60
148+
traceback.print_exc(file=sys.stdout)
149+
print '-'*60
150+
151+
envdir = {}
152+
while 1:
153+
run_user_code(envdir)
154+
\end{verbatim}

0 commit comments

Comments
 (0)
0