1 \section{\module{traceback
} ---
2 Print or retrieve a stack traceback
}
4 \declaremodule{standard
}{traceback
}
5 \modulesynopsis{Print or retrieve a stack traceback.
}
8 This module provides a standard interface to extract, format and print
9 stack traces of Python programs. It exactly mimics the behavior of
10 the Python interpreter when it prints a stack trace. This is useful
11 when you want to print stack traces under program control, such as in a
12 ``wrapper'' around the interpreter.
14 The module uses traceback objects --- this is the object type that is
15 stored in the variables
\code{sys.exc_traceback
} (deprecated) and
16 \code{sys.last_traceback
} and returned as the third item from
17 \function{sys.exc_info()
}.
20 The module defines the following functions:
22 \begin{funcdesc
}{print_tb
}{traceback
\optional{, limit
\optional{, file
}}}
23 Print up to
\var{limit
} stack trace entries from
\var{traceback
}. If
24 \var{limit
} is omitted or
\code{None
}, all entries are printed.
25 If
\var{file
} is omitted or
\code{None
}, the output goes to
26 \code{sys.stderr
}; otherwise it should be an open file or file-like
27 object to receive the output.
30 \begin{funcdesc
}{print_exception
}{type, value, traceback
\optional{,
31 limit
\optional{, file
}}}
32 Print exception information and up to
\var{limit
} stack trace entries
33 from
\var{traceback
} to
\var{file
}.
34 This differs from
\function{print_tb()
} in the
35 following ways: (
1) if
\var{traceback
} is not
\code{None
}, it prints a
36 header
\samp{Traceback (most recent call last):
}; (
2) it prints the
37 exception
\var{type
} and
\var{value
} after the stack trace; (
3) if
38 \var{type
} is
\exception{SyntaxError
} and
\var{value
} has the
39 appropriate format, it prints the line where the syntax error occurred
40 with a caret indicating the approximate position of the error.
43 \begin{funcdesc
}{print_exc
}{\optional{limit
\optional{, file
}}}
44 This is a shorthand for
\code{print_exception(sys.exc_type,
45 sys.exc_value, sys.exc_traceback,
\var{limit
},
\var{file
})
}. (In
46 fact, it uses
\function{sys.exc_info()
} to retrieve the same
47 information in a thread-safe way instead of using the deprecated
51 \begin{funcdesc
}{format_exc
}{\optional{limit
}}
52 This is like
\code{print_exc(
\var{limit
})
} but returns a string
53 instead of printing to a file.
57 \begin{funcdesc
}{print_last
}{\optional{limit
\optional{, file
}}}
58 This is a shorthand for
\code{print_exception(sys.last_type,
59 sys.last_value, sys.last_traceback,
\var{limit
},
\var{file
})
}.
62 \begin{funcdesc
}{print_stack
}{\optional{f
\optional{, limit
\optional{, file
}}}}
63 This function prints a stack trace from its invocation point. The
64 optional
\var{f
} argument can be used to specify an alternate stack
65 frame to start. The optional
\var{limit
} and
\var{file
} arguments have the
66 same meaning as for
\function{print_exception()
}.
69 \begin{funcdesc
}{extract_tb
}{traceback
\optional{, limit
}}
70 Return a list of up to
\var{limit
} ``pre-processed'' stack trace
71 entries extracted from the traceback object
\var{traceback
}. It is
72 useful for alternate formatting of stack traces. If
\var{limit
} is
73 omitted or
\code{None
}, all entries are extracted. A
74 ``pre-processed'' stack trace entry is a quadruple (
\var{filename
},
75 \var{line number
},
\var{function name
},
\var{text
}) representing
76 the information that is usually printed for a stack trace. The
77 \var{text
} is a string with leading and trailing whitespace
78 stripped; if the source is not available it is
\code{None
}.
81 \begin{funcdesc
}{extract_stack
}{\optional{f
\optional{, limit
}}}
82 Extract the raw traceback from the current stack frame. The return
83 value has the same format as for
\function{extract_tb()
}. The
84 optional
\var{f
} and
\var{limit
} arguments have the same meaning as
85 for
\function{print_stack()
}.
88 \begin{funcdesc
}{format_list
}{list
}
89 Given a list of tuples as returned by
\function{extract_tb()
} or
90 \function{extract_stack()
}, return a list of strings ready for
91 printing. Each string in the resulting list corresponds to the item
92 with the same index in the argument list. Each string ends in a
93 newline; the strings may contain internal newlines as well, for those
94 items whose source text line is not
\code{None
}.
97 \begin{funcdesc
}{format_exception_only
}{type, value
}
98 Format the exception part of a traceback. The arguments are the
99 exception type and value such as given by
\code{sys.last_type
} and
100 \code{sys.last_value
}. The return value is a list of strings, each
101 ending in a newline. Normally, the list contains a single string;
102 however, for
\exception{SyntaxError
} exceptions, it contains several
103 lines that (when printed) display detailed information about where the
104 syntax error occurred. The message indicating which exception
105 occurred is the always last string in the list.
108 \begin{funcdesc
}{format_exception
}{type, value, tb
\optional{, limit
}}
109 Format a stack trace and the exception information. The arguments
110 have the same meaning as the corresponding arguments to
111 \function{print_exception()
}. The return value is a list of strings,
112 each ending in a newline and some containing internal newlines. When
113 these lines are concatenated and printed, exactly the same text is
114 printed as does
\function{print_exception()
}.
117 \begin{funcdesc
}{format_tb
}{tb
\optional{, limit
}}
118 A shorthand for
\code{format_list(extract_tb(
\var{tb
},
\var{limit
}))
}.
121 \begin{funcdesc
}{format_stack
}{\optional{f
\optional{, limit
}}}
122 A shorthand for
\code{format_list(extract_stack(
\var{f
},
\var{limit
}))
}.
125 \begin{funcdesc
}{tb_lineno
}{tb
}
126 This function returns the current line number set in the traceback
127 object. This function was necessary because in versions of Python
128 prior to
2.3 when the
\programopt{-O
} flag was passed to Python the
129 \code{\var{tb
}.tb_lineno
} was not updated correctly. This function
130 has no use in versions past
2.3.
134 \subsection{Traceback Example
\label{traceback-example
}}
136 This simple example implements a basic read-eval-print loop, similar
137 to (but less useful than) the standard Python interactive interpreter
138 loop. For a more complete implementation of the interpreter loop,
139 refer to the
\refmodule{code
} module.
142 import sys, traceback
144 def run_user_code(envdir):
145 source = raw_input(">>> ")
147 exec source in envdir
149 print "Exception in user code:"
151 traceback.print_exc(file=sys.stdout)
156 run_user_code(envdir)