Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame^] | 1 | \section{\module{traceback} --- |
| 2 | Print or retrieve a stack traceback.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | \declaremodule{standard}{traceback} |
| 4 | |
| 5 | \modulesynopsis{Print or retrieve a stack traceback.} |
| 6 | |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 7 | |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 8 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 9 | This module provides a standard interface to extract, format and print |
| 10 | stack traces of Python programs. It exactly mimics the behavior of |
| 11 | the Python interpreter when it prints a stack trace. This is useful |
| 12 | 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] | 13 | ``wrapper'' around the interpreter. |
| 14 | |
| 15 | The module uses traceback objects --- this is the object type |
| 16 | that is stored in the variables \code{sys.exc_traceback} and |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 17 | \code{sys.last_traceback} and returned as the third item from |
| 18 | \function{sys.exc_info()}. |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 19 | \obindex{traceback} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 20 | |
| 21 | The module defines the following functions: |
| 22 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 23 | \begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 24 | Print up to \var{limit} stack trace entries from \var{traceback}. If |
| 25 | \var{limit} is omitted or \code{None}, all entries are printed. |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 26 | If \var{file} is omitted or \code{None}, the output goes to |
| 27 | \code{sys.stderr}; otherwise it should be an open file or file-like |
| 28 | object to receive the output. |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 29 | \end{funcdesc} |
| 30 | |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 31 | \begin{funcdesc}{extract_tb}{traceback\optional{, limit}} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 32 | Return a list of up to \var{limit} ``pre-processed'' stack trace |
| 33 | entries extracted from \var{traceback}. It is useful for alternate |
| 34 | formatting of stack traces. If \var{limit} is omitted or \code{None}, |
| 35 | all entries are extracted. A ``pre-processed'' stack trace entry is a |
| 36 | quadruple (\var{filename}, \var{line number}, \var{function name}, |
| 37 | \var{line text}) representing the information that is usually printed |
| 38 | for a stack trace. The \var{line text} is a string with leading and |
| 39 | trailing whitespace stripped; if the source is not available it is |
| 40 | \code{None}. |
| 41 | \end{funcdesc} |
| 42 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 43 | \begin{funcdesc}{print_exception}{type, value, |
| 44 | traceback\optional{, limit\optional{, file}}} |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 45 | Print exception information and up to \var{limit} stack trace entries |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 46 | from \var{traceback} to \var{file}. |
| 47 | This differs from \function{print_tb()} in the |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 48 | 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] | 49 | header \samp{Traceback (innermost last):}; (2) it prints the |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 50 | exception \var{type} and \var{value} after the stack trace; (3) if |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 51 | \var{type} is \exception{SyntaxError} and \var{value} has the appropriate |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 52 | format, it prints the line where the syntax error occurred with a |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 53 | caret indicating the approximate position of the error. |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 54 | \end{funcdesc} |
| 55 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 56 | \begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}} |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 57 | This is a shorthand for `\code{print_exception(sys.exc_type,} |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 58 | \code{sys.exc_value,} \code{sys.exc_traceback,} \var{limit}\code{,} |
| 59 | \var{file}\code{)}'. (In fact, it uses \code{sys.exc_info()} to |
| 60 | retrieve the same information in a thread-safe way.) |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 61 | \end{funcdesc} |
| 62 | |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 63 | \begin{funcdesc}{print_last}{\optional{limit\optional{, file}}} |
Fred Drake | 266b4c1 | 1998-03-08 06:12:10 +0000 | [diff] [blame] | 64 | This is a shorthand for `\code{print_exception(sys.last_type,} |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 65 | \code{sys.last_value,} \code{sys.last_traceback,} \var{limit}\code{,} |
| 66 | \var{file}\code{)}'. |
Guido van Rossum | 81b3060 | 1995-03-01 14:36:00 +0000 | [diff] [blame] | 67 | \end{funcdesc} |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 68 | |
| 69 | \begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}} |
| 70 | This function prints a stack trace from its invocation point. The |
| 71 | optional \var{f} argument can be used to specify an alternate stack |
| 72 | frame to start. The optional \var{limit} and \var{file} arguments have the |
| 73 | same meaning as for \function{print_exception()}. |
| 74 | \end{funcdesc} |
| 75 | |
| 76 | \begin{funcdesc}{extract_tb}{tb\optional{, limit}} |
| 77 | Return a list containing the raw (unformatted) traceback information |
| 78 | extracted from the traceback object \var{tb}. The optional |
| 79 | \var{limit} argument has the same meaning as for |
| 80 | \function{print_exception()}. The items in the returned list are |
| 81 | 4-tuples containing the following values: filename, line number, |
| 82 | function name, and source text line. The source text line is stripped |
| 83 | of leading and trailing whitespace; it is \code{None} when the source |
| 84 | text file is unavailable. |
| 85 | \end{funcdesc} |
| 86 | |
| 87 | \begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}} |
| 88 | Extract the raw traceback from the current stack frame. The return |
| 89 | value has the same format as for \function{extract_tb()}. The |
| 90 | optional \var{f} and \var{limit} arguments have the same meaning as |
| 91 | for \function{print_stack()}. |
| 92 | \end{funcdesc} |
| 93 | |
| 94 | \begin{funcdesc}{format_list}{list} |
| 95 | Given a list of tuples as returned by \function{extract_tb()} or |
| 96 | \function{extract_stack()}, return a list of strings ready for |
| 97 | printing. Each string in the resulting list corresponds to the item |
| 98 | with the same index in the argument list. Each string ends in a |
| 99 | newline; the strings may contain internal newlines as well, for those |
| 100 | items whose source text line is not \code{None}. |
| 101 | \end{funcdesc} |
| 102 | |
| 103 | \begin{funcdesc}{format_exception_only}{type, value} |
| 104 | Format the exception part of a traceback. The arguments are the |
| 105 | exception type and value such as given by \code{sys.last_type} and |
| 106 | \code{sys.last_value}. The return value is a list of strings, each |
| 107 | ending in a newline. Normally, the list contains a single string; |
| 108 | however, for \code{SyntaxError} exceptions, it contains several lines |
| 109 | that (when printed) display detailed information about where the |
| 110 | syntax error occurred. The message indicating which exception |
| 111 | occurred is the always last string in the list. |
| 112 | \end{funcdesc} |
| 113 | |
| 114 | \begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}} |
| 115 | Format a stack trace and the exception information. The arguments |
| 116 | have the same meaning as the corresponding arguments to |
| 117 | \function{print_exception()}. The return value is a list of strings, |
| 118 | each ending in a newline and some containing internal newlines. When |
| 119 | these lines are contatenated and printed, exactly the same text is |
| 120 | printed as does \function{print_exception()}. |
| 121 | \end{funcdesc} |
| 122 | |
| 123 | \begin{funcdesc}{format_tb}{tb\optional{, limit}} |
| 124 | A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}. |
| 125 | \end{funcdesc} |
| 126 | |
| 127 | \begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}} |
| 128 | A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}. |
| 129 | \end{funcdesc} |
| 130 | |
| 131 | \begin{funcdesc}{tb_lineno}{tb} |
| 132 | This function returns the current line number set in the traceback |
| 133 | object. This is normally the same as the \code{\var{tb}.tb_lineno} |
| 134 | field of the object, but when optimization is used (the -O flag) this |
| 135 | field is not updated correctly; this function calculates the correct |
| 136 | value. |
| 137 | \end{funcdesc} |
| 138 | |
| 139 | A simple example follows: |
| 140 | |
| 141 | \begin{verbatim} |
| 142 | import sys, traceback |
| 143 | |
| 144 | def run_user_code(envdir): |
| 145 | source = raw_input(">>> ") |
| 146 | try: |
| 147 | exec source in envdir |
| 148 | except: |
| 149 | print "Exception in user code:" |
Guido van Rossum | faac013 | 1998-06-17 22:38:09 +0000 | [diff] [blame] | 150 | print '-'*60 |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 151 | traceback.print_exc(file=sys.stdout) |
Guido van Rossum | faac013 | 1998-06-17 22:38:09 +0000 | [diff] [blame] | 152 | print '-'*60 |
Guido van Rossum | bca1207 | 1998-06-17 22:37:26 +0000 | [diff] [blame] | 153 | |
| 154 | envdir = {} |
| 155 | while 1: |
| 156 | run_user_code(envdir) |
| 157 | \end{verbatim} |