Fred Drake | 3a0351c | 1998-04-04 07:23:21 +0000 | [diff] [blame] | 1 | \section{Standard Module \module{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 | |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 5 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 10 | ``wrapper'' around the interpreter. |
| 11 | |
| 12 | The module uses traceback objects --- this is the object type |
| 13 | that is stored in the variables \code{sys.exc_traceback} and |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 14 | \code{sys.last_traceback} and returned as the third item from |
| 15 | \function{sys.exc_info()}. |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 16 | \obindex{traceback} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 17 | |
| 18 | The module defines the following functions: |
| 19 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 20 | \begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 21 | Print up to \var{limit} stack trace entries from \var{traceback}. If |
| 22 | \var{limit} is omitted or \code{None}, all entries are printed. |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 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. |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 26 | \end{funcdesc} |
| 27 | |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 28 | \begin{funcdesc}{extract_tb}{traceback\optional{, limit}} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 29 | Return a list of up to \var{limit} ``pre-processed'' stack trace |
| 30 | entries extracted from \var{traceback}. It is useful for alternate |
| 31 | formatting of stack traces. If \var{limit} is omitted or \code{None}, |
| 32 | all entries are extracted. A ``pre-processed'' stack trace entry is a |
| 33 | quadruple (\var{filename}, \var{line number}, \var{function name}, |
| 34 | \var{line text}) representing the information that is usually printed |
| 35 | for a stack trace. The \var{line text} is a string with leading and |
| 36 | trailing whitespace stripped; if the source is not available it is |
| 37 | \code{None}. |
| 38 | \end{funcdesc} |
| 39 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 40 | \begin{funcdesc}{print_exception}{type, value, |
| 41 | traceback\optional{, limit\optional{, file}}} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 42 | Print exception information and up to \var{limit} stack trace entries |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 43 | from \var{traceback} to \var{file}. |
| 44 | This differs from \function{print_tb()} in the |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 45 | following ways: (1) if \var{traceback} is not \code{None}, it prints a |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 46 | header \samp{Traceback (innermost last):}; (2) it prints the |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 47 | exception \var{type} and \var{value} after the stack trace; (3) if |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 48 | \var{type} is \exception{SyntaxError} and \var{value} has the appropriate |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 49 | format, it prints the line where the syntax error occurred with a |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 50 | caret indicating the approximate position of the error. |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 51 | \end{funcdesc} |
| 52 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 53 | \begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}} |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 54 | This is a shorthand for `\code{print_exception(sys.exc_type,} |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 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.) |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 58 | \end{funcdesc} |
| 59 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 60 | \begin{funcdesc}{print_last}{\optional{limit\optional{, file}}} |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 61 | This is a shorthand for `\code{print_exception(sys.last_type,} |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 62 | \code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{,} |
| 63 | \var{file}\code{)}'. |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 64 | \end{funcdesc} |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 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:" |
Guido van Rossum | faac013 | 1998-06-17 22:38:09 +0000 | [diff] [blame] | 147 | print '-'*60 |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 148 | traceback.print_exc(file=sys.stdout) |
Guido van Rossum | faac013 | 1998-06-17 22:38:09 +0000 | [diff] [blame] | 149 | print '-'*60 |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 150 | |
| 151 | envdir = {} |
| 152 | while 1: |
| 153 | run_user_code(envdir) |
| 154 | \end{verbatim} |