Guido van Rossum | e7b146f | 2000-02-04 15:28:42 +0000 | [diff] [blame] | 1 | """Extract, format and print information about Python stack traces.""" |
Guido van Rossum | 526beed | 1994-07-01 15:36:46 +0000 | [diff] [blame] | 2 | |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 3 | import collections |
| 4 | import itertools |
Guido van Rossum | 526beed | 1994-07-01 15:36:46 +0000 | [diff] [blame] | 5 | import linecache |
Guido van Rossum | 526beed | 1994-07-01 15:36:46 +0000 | [diff] [blame] | 6 | import sys |
| 7 | |
Skip Montanaro | 40fc160 | 2001-03-01 04:27:19 +0000 | [diff] [blame] | 8 | __all__ = ['extract_stack', 'extract_tb', 'format_exception', |
| 9 | 'format_exception_only', 'format_list', 'format_stack', |
Neil Schemenauer | f607fc5 | 2003-11-05 23:03:00 +0000 | [diff] [blame] | 10 | 'format_tb', 'print_exc', 'format_exc', 'print_exception', |
Berker Peksag | 716b3d3 | 2015-04-08 09:47:14 +0300 | [diff] [blame] | 11 | 'print_last', 'print_stack', 'print_tb', 'clear_frames', |
| 12 | 'FrameSummary', 'StackSummary', 'TracebackException', |
| 13 | 'walk_stack', 'walk_tb'] |
Skip Montanaro | 40fc160 | 2001-03-01 04:27:19 +0000 | [diff] [blame] | 14 | |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 15 | # |
| 16 | # Formatting and printing lists of traceback lines. |
| 17 | # |
Guido van Rossum | dcc057a | 1996-08-12 23:18:13 +0000 | [diff] [blame] | 18 | |
Guido van Rossum | dcc057a | 1996-08-12 23:18:13 +0000 | [diff] [blame] | 19 | def print_list(extracted_list, file=None): |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 20 | """Print the list of tuples as returned by extract_tb() or |
| 21 | extract_stack() as a formatted stack trace to the given file.""" |
Raymond Hettinger | 10ff706 | 2002-06-02 03:04:52 +0000 | [diff] [blame] | 22 | if file is None: |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 23 | file = sys.stderr |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 24 | for item in StackSummary.from_list(extracted_list).format(): |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 25 | print(item, file=file, end="") |
Guido van Rossum | dcc057a | 1996-08-12 23:18:13 +0000 | [diff] [blame] | 26 | |
| 27 | def format_list(extracted_list): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 28 | """Format a list of traceback entry tuples for printing. |
| 29 | |
| 30 | Given a list of tuples as returned by extract_tb() or |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 31 | extract_stack(), return a list of strings ready for printing. |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 32 | Each string in the resulting list corresponds to the item with the |
| 33 | same index in the argument list. Each string ends in a newline; |
| 34 | the strings may contain internal newlines as well, for those items |
| 35 | whose source text line is not None. |
| 36 | """ |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 37 | return StackSummary.from_list(extracted_list).format() |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 38 | |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 39 | # |
| 40 | # Printing and Extracting Tracebacks. |
| 41 | # |
| 42 | |
Guido van Rossum | 194e20a | 1995-09-20 20:31:51 +0000 | [diff] [blame] | 43 | def print_tb(tb, limit=None, file=None): |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 44 | """Print up to 'limit' stack trace entries from the traceback 'tb'. |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 45 | |
| 46 | If 'limit' is omitted or None, all entries are printed. If 'file' |
| 47 | is omitted or None, the output goes to sys.stderr; otherwise |
| 48 | 'file' should be an open file or file-like object with a write() |
| 49 | method. |
| 50 | """ |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 51 | print_list(extract_tb(tb, limit=limit), file=file) |
Guido van Rossum | 526beed | 1994-07-01 15:36:46 +0000 | [diff] [blame] | 52 | |
Georg Brandl | 2ad07c3 | 2009-09-16 14:24:29 +0000 | [diff] [blame] | 53 | def format_tb(tb, limit=None): |
Georg Brandl | 9e091e1 | 2013-10-13 23:32:14 +0200 | [diff] [blame] | 54 | """A shorthand for 'format_list(extract_tb(tb, limit))'.""" |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 55 | return extract_tb(tb, limit=limit).format() |
Guido van Rossum | 28e99fe | 1995-08-04 04:30:30 +0000 | [diff] [blame] | 56 | |
Georg Brandl | 2ad07c3 | 2009-09-16 14:24:29 +0000 | [diff] [blame] | 57 | def extract_tb(tb, limit=None): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 58 | """Return list of up to limit pre-processed entries from traceback. |
| 59 | |
| 60 | This is useful for alternate formatting of stack traces. If |
| 61 | 'limit' is omitted or None, all entries are extracted. A |
| 62 | pre-processed stack trace entry is a quadruple (filename, line |
| 63 | number, function name, text) representing the information that is |
| 64 | usually printed for a stack trace. The text is a string with |
| 65 | leading and trailing whitespace stripped; if the source is not |
| 66 | available it is None. |
| 67 | """ |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 68 | return StackSummary.extract(walk_tb(tb), limit=limit) |
Guido van Rossum | 526beed | 1994-07-01 15:36:46 +0000 | [diff] [blame] | 69 | |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 70 | # |
| 71 | # Exception formatting and output. |
| 72 | # |
Guido van Rossum | 28e99fe | 1995-08-04 04:30:30 +0000 | [diff] [blame] | 73 | |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 74 | _cause_message = ( |
| 75 | "\nThe above exception was the direct cause " |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 76 | "of the following exception:\n\n") |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 77 | |
| 78 | _context_message = ( |
| 79 | "\nDuring handling of the above exception, " |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 80 | "another exception occurred:\n\n") |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 81 | |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 82 | |
| 83 | def print_exception(etype, value, tb, limit=None, file=None, chain=True): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 84 | """Print exception up to 'limit' stack trace entries from 'tb' to 'file'. |
| 85 | |
| 86 | This differs from print_tb() in the following ways: (1) if |
| 87 | traceback is not None, it prints a header "Traceback (most recent |
| 88 | call last):"; (2) it prints the exception type and value after the |
| 89 | stack trace; (3) if type is SyntaxError and value has the |
| 90 | appropriate format, it prints the line where the syntax error |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 91 | occurred with a caret on the next line indicating the approximate |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 92 | position of the error. |
| 93 | """ |
Robert Collins | 2f0441f | 2015-03-05 15:45:01 +1300 | [diff] [blame] | 94 | # format_exception has ignored etype for some time, and code such as cgitb |
| 95 | # passes in bogus values as a result. For compatibility with such code we |
| 96 | # ignore it here (rather than in the new TracebackException API). |
Raymond Hettinger | 10ff706 | 2002-06-02 03:04:52 +0000 | [diff] [blame] | 97 | if file is None: |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 98 | file = sys.stderr |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 99 | for line in TracebackException( |
Robert Collins | 2f0441f | 2015-03-05 15:45:01 +1300 | [diff] [blame] | 100 | type(value), value, tb, limit=limit).format(chain=chain): |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 101 | print(line, file=file, end="") |
Guido van Rossum | 28e99fe | 1995-08-04 04:30:30 +0000 | [diff] [blame] | 102 | |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 103 | |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 104 | def format_exception(etype, value, tb, limit=None, chain=True): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 105 | """Format a stack trace and the exception information. |
| 106 | |
| 107 | The arguments have the same meaning as the corresponding arguments |
| 108 | to print_exception(). The return value is a list of strings, each |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 109 | ending in a newline and some containing internal newlines. When |
| 110 | these lines are concatenated and printed, exactly the same text is |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 111 | printed as does print_exception(). |
| 112 | """ |
Robert Collins | 2f0441f | 2015-03-05 15:45:01 +1300 | [diff] [blame] | 113 | # format_exception has ignored etype for some time, and code such as cgitb |
| 114 | # passes in bogus values as a result. For compatibility with such code we |
| 115 | # ignore it here (rather than in the new TracebackException API). |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 116 | return list(TracebackException( |
Robert Collins | 2f0441f | 2015-03-05 15:45:01 +1300 | [diff] [blame] | 117 | type(value), value, tb, limit=limit).format(chain=chain)) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 118 | |
Guido van Rossum | 28e99fe | 1995-08-04 04:30:30 +0000 | [diff] [blame] | 119 | |
| 120 | def format_exception_only(etype, value): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 121 | """Format the exception part of a traceback. |
| 122 | |
| 123 | The arguments are the exception type and value such as given by |
| 124 | sys.last_type and sys.last_value. The return value is a list of |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 125 | strings, each ending in a newline. |
| 126 | |
| 127 | Normally, the list contains a single string; however, for |
| 128 | SyntaxError exceptions, it contains several lines that (when |
| 129 | printed) display detailed information about where the syntax |
| 130 | error occurred. |
| 131 | |
| 132 | The message indicating which exception occurred is always the last |
| 133 | string in the list. |
| 134 | |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 135 | """ |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 136 | return list(TracebackException(etype, value, None).format_exception_only()) |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 137 | |
Thomas Wouters | 89f507f | 2006-12-13 04:49:30 +0000 | [diff] [blame] | 138 | |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 139 | # -- not offical API but folk probably use these two functions. |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 140 | |
| 141 | def _format_final_exc_line(etype, value): |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 142 | valuestr = _some_str(value) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 143 | if value == 'None' or value is None or not valuestr: |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 144 | line = "%s\n" % etype |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 145 | else: |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 146 | line = "%s: %s\n" % (etype, valuestr) |
| 147 | return line |
Guido van Rossum | 28e99fe | 1995-08-04 04:30:30 +0000 | [diff] [blame] | 148 | |
Guido van Rossum | 2823f03 | 2000-08-22 02:04:46 +0000 | [diff] [blame] | 149 | def _some_str(value): |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 150 | try: |
| 151 | return str(value) |
| 152 | except: |
| 153 | return '<unprintable %s object>' % type(value).__name__ |
Guido van Rossum | 2823f03 | 2000-08-22 02:04:46 +0000 | [diff] [blame] | 154 | |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 155 | # -- |
| 156 | |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 157 | def print_exc(limit=None, file=None, chain=True): |
Neal Norwitz | ac3625f | 2006-03-17 05:49:33 +0000 | [diff] [blame] | 158 | """Shorthand for 'print_exception(*sys.exc_info(), limit, file)'.""" |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 159 | print_exception(*sys.exc_info(), limit=limit, file=file, chain=chain) |
Neil Schemenauer | f607fc5 | 2003-11-05 23:03:00 +0000 | [diff] [blame] | 160 | |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 161 | def format_exc(limit=None, chain=True): |
Neil Schemenauer | f607fc5 | 2003-11-05 23:03:00 +0000 | [diff] [blame] | 162 | """Like print_exc() but return a string.""" |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 163 | return "".join(format_exception(*sys.exc_info(), limit=limit, chain=chain)) |
Neil Schemenauer | f607fc5 | 2003-11-05 23:03:00 +0000 | [diff] [blame] | 164 | |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 165 | def print_last(limit=None, file=None, chain=True): |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 166 | """This is a shorthand for 'print_exception(sys.last_type, |
| 167 | sys.last_value, sys.last_traceback, limit, file)'.""" |
Benjamin Peterson | e549ead | 2009-03-28 21:42:05 +0000 | [diff] [blame] | 168 | if not hasattr(sys, "last_type"): |
| 169 | raise ValueError("no last exception") |
Tim Peters | b90f89a | 2001-01-15 03:26:36 +0000 | [diff] [blame] | 170 | print_exception(sys.last_type, sys.last_value, sys.last_traceback, |
Benjamin Peterson | e652821 | 2008-07-15 15:32:09 +0000 | [diff] [blame] | 171 | limit, file, chain) |
Guido van Rossum | dcc057a | 1996-08-12 23:18:13 +0000 | [diff] [blame] | 172 | |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 173 | # |
| 174 | # Printing and Extracting Stacks. |
| 175 | # |
| 176 | |
Guido van Rossum | dcc057a | 1996-08-12 23:18:13 +0000 | [diff] [blame] | 177 | def print_stack(f=None, limit=None, file=None): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 178 | """Print a stack trace from its invocation point. |
Tim Peters | a19a168 | 2001-03-29 04:36:09 +0000 | [diff] [blame] | 179 | |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 180 | The optional 'f' argument can be used to specify an alternate |
| 181 | stack frame at which to start. The optional 'limit' and 'file' |
| 182 | arguments have the same meaning as for print_exception(). |
| 183 | """ |
Serhiy Storchaka | e953ba7 | 2015-09-18 10:04:47 +0300 | [diff] [blame] | 184 | if f is None: |
| 185 | f = sys._getframe().f_back |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 186 | print_list(extract_stack(f, limit=limit), file=file) |
| 187 | |
Guido van Rossum | dcc057a | 1996-08-12 23:18:13 +0000 | [diff] [blame] | 188 | |
| 189 | def format_stack(f=None, limit=None): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 190 | """Shorthand for 'format_list(extract_stack(f, limit))'.""" |
Serhiy Storchaka | e953ba7 | 2015-09-18 10:04:47 +0300 | [diff] [blame] | 191 | if f is None: |
| 192 | f = sys._getframe().f_back |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 193 | return format_list(extract_stack(f, limit=limit)) |
| 194 | |
Guido van Rossum | dcc057a | 1996-08-12 23:18:13 +0000 | [diff] [blame] | 195 | |
Georg Brandl | 2ad07c3 | 2009-09-16 14:24:29 +0000 | [diff] [blame] | 196 | def extract_stack(f=None, limit=None): |
Jeremy Hylton | 69e9e8b | 2001-03-21 19:09:31 +0000 | [diff] [blame] | 197 | """Extract the raw traceback from the current stack frame. |
| 198 | |
| 199 | The return value has the same format as for extract_tb(). The |
| 200 | optional 'f' and 'limit' arguments have the same meaning as for |
| 201 | print_stack(). Each item in the list is a quadruple (filename, |
| 202 | line number, function name, text), and the entries are in order |
| 203 | from oldest to newest stack frame. |
| 204 | """ |
Serhiy Storchaka | e953ba7 | 2015-09-18 10:04:47 +0300 | [diff] [blame] | 205 | if f is None: |
| 206 | f = sys._getframe().f_back |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 207 | stack = StackSummary.extract(walk_stack(f), limit=limit) |
Benjamin Peterson | d9fec15 | 2013-04-29 16:09:39 -0400 | [diff] [blame] | 208 | stack.reverse() |
| 209 | return stack |
Andrew Kuchling | 173a157 | 2013-09-15 18:15:56 -0400 | [diff] [blame] | 210 | |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 211 | |
Andrew Kuchling | 173a157 | 2013-09-15 18:15:56 -0400 | [diff] [blame] | 212 | def clear_frames(tb): |
| 213 | "Clear all references to local variables in the frames of a traceback." |
| 214 | while tb is not None: |
| 215 | try: |
| 216 | tb.tb_frame.clear() |
| 217 | except RuntimeError: |
| 218 | # Ignore the exception raised if the frame is still executing. |
| 219 | pass |
| 220 | tb = tb.tb_next |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 221 | |
| 222 | |
| 223 | class FrameSummary: |
| 224 | """A single frame from a traceback. |
| 225 | |
| 226 | - :attr:`filename` The filename for the frame. |
| 227 | - :attr:`lineno` The line within filename for the frame that was |
| 228 | active when the frame was captured. |
| 229 | - :attr:`name` The name of the function or method that was executing |
| 230 | when the frame was captured. |
| 231 | - :attr:`line` The text from the linecache module for the |
| 232 | of code that was running when the frame was captured. |
| 233 | - :attr:`locals` Either None if locals were not supplied, or a dict |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 234 | mapping the name to the repr() of the variable. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 235 | """ |
| 236 | |
| 237 | __slots__ = ('filename', 'lineno', 'name', '_line', 'locals') |
| 238 | |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 239 | def __init__(self, filename, lineno, name, *, lookup_line=True, |
| 240 | locals=None, line=None): |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 241 | """Construct a FrameSummary. |
| 242 | |
| 243 | :param lookup_line: If True, `linecache` is consulted for the source |
| 244 | code line. Otherwise, the line will be looked up when first needed. |
| 245 | :param locals: If supplied the frame locals, which will be captured as |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 246 | object representations. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 247 | :param line: If provided, use this instead of looking up the line in |
| 248 | the linecache. |
| 249 | """ |
| 250 | self.filename = filename |
| 251 | self.lineno = lineno |
| 252 | self.name = name |
| 253 | self._line = line |
| 254 | if lookup_line: |
| 255 | self.line |
| 256 | self.locals = \ |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 257 | dict((k, repr(v)) for k, v in locals.items()) if locals else None |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 258 | |
| 259 | def __eq__(self, other): |
Serhiy Storchaka | 3066fc4 | 2015-09-29 22:33:36 +0300 | [diff] [blame] | 260 | if isinstance(other, FrameSummary): |
| 261 | return (self.filename == other.filename and |
| 262 | self.lineno == other.lineno and |
| 263 | self.name == other.name and |
| 264 | self.locals == other.locals) |
| 265 | if isinstance(other, tuple): |
| 266 | return (self.filename, self.lineno, self.name, self.line) == other |
| 267 | return NotImplemented |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 268 | |
| 269 | def __getitem__(self, pos): |
| 270 | return (self.filename, self.lineno, self.name, self.line)[pos] |
| 271 | |
| 272 | def __iter__(self): |
| 273 | return iter([self.filename, self.lineno, self.name, self.line]) |
| 274 | |
| 275 | def __repr__(self): |
| 276 | return "<FrameSummary file {filename}, line {lineno} in {name}>".format( |
| 277 | filename=self.filename, lineno=self.lineno, name=self.name) |
| 278 | |
| 279 | @property |
| 280 | def line(self): |
| 281 | if self._line is None: |
| 282 | self._line = linecache.getline(self.filename, self.lineno).strip() |
| 283 | return self._line |
| 284 | |
| 285 | |
| 286 | def walk_stack(f): |
| 287 | """Walk a stack yielding the frame and line number for each frame. |
| 288 | |
| 289 | This will follow f.f_back from the given frame. If no frame is given, the |
| 290 | current stack is used. Usually used with StackSummary.extract. |
| 291 | """ |
| 292 | if f is None: |
| 293 | f = sys._getframe().f_back.f_back |
| 294 | while f is not None: |
| 295 | yield f, f.f_lineno |
| 296 | f = f.f_back |
| 297 | |
| 298 | |
| 299 | def walk_tb(tb): |
| 300 | """Walk a traceback yielding the frame and line number for each frame. |
| 301 | |
| 302 | This will follow tb.tb_next (and thus is in the opposite order to |
| 303 | walk_stack). Usually used with StackSummary.extract. |
| 304 | """ |
| 305 | while tb is not None: |
| 306 | yield tb.tb_frame, tb.tb_lineno |
| 307 | tb = tb.tb_next |
| 308 | |
| 309 | |
| 310 | class StackSummary(list): |
| 311 | """A stack of frames.""" |
| 312 | |
| 313 | @classmethod |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 314 | def extract(klass, frame_gen, *, limit=None, lookup_lines=True, |
| 315 | capture_locals=False): |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 316 | """Create a StackSummary from a traceback or stack object. |
| 317 | |
| 318 | :param frame_gen: A generator that yields (frame, lineno) tuples to |
| 319 | include in the stack. |
| 320 | :param limit: None to include all frames or the number of frames to |
| 321 | include. |
| 322 | :param lookup_lines: If True, lookup lines for each frame immediately, |
| 323 | otherwise lookup is deferred until the frame is rendered. |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 324 | :param capture_locals: If True, the local variables from each frame will |
| 325 | be captured as object representations into the FrameSummary. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 326 | """ |
| 327 | if limit is None: |
| 328 | limit = getattr(sys, 'tracebacklimit', None) |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 329 | if limit is not None and limit < 0: |
| 330 | limit = 0 |
| 331 | if limit is not None: |
| 332 | if limit >= 0: |
| 333 | frame_gen = itertools.islice(frame_gen, limit) |
| 334 | else: |
| 335 | frame_gen = collections.deque(frame_gen, maxlen=-limit) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 336 | |
| 337 | result = klass() |
| 338 | fnames = set() |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 339 | for f, lineno in frame_gen: |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 340 | co = f.f_code |
| 341 | filename = co.co_filename |
| 342 | name = co.co_name |
| 343 | |
| 344 | fnames.add(filename) |
| 345 | linecache.lazycache(filename, f.f_globals) |
| 346 | # Must defer line lookups until we have called checkcache. |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 347 | if capture_locals: |
| 348 | f_locals = f.f_locals |
| 349 | else: |
| 350 | f_locals = None |
| 351 | result.append(FrameSummary( |
| 352 | filename, lineno, name, lookup_line=False, locals=f_locals)) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 353 | for filename in fnames: |
| 354 | linecache.checkcache(filename) |
| 355 | # If immediate lookup was desired, trigger lookups now. |
| 356 | if lookup_lines: |
| 357 | for f in result: |
| 358 | f.line |
| 359 | return result |
| 360 | |
| 361 | @classmethod |
| 362 | def from_list(klass, a_list): |
| 363 | """Create a StackSummary from a simple list of tuples. |
| 364 | |
| 365 | This method supports the older Python API. Each tuple should be a |
| 366 | 4-tuple with (filename, lineno, name, line) elements. |
| 367 | """ |
Robert Collins | bbb8ade | 2015-03-16 15:27:16 +1300 | [diff] [blame] | 368 | # While doing a fast-path check for isinstance(a_list, StackSummary) is |
| 369 | # appealing, idlelib.run.cleanup_traceback and other similar code may |
| 370 | # break this by making arbitrary frames plain tuples, so we need to |
| 371 | # check on a frame by frame basis. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 372 | result = StackSummary() |
Robert Collins | bbb8ade | 2015-03-16 15:27:16 +1300 | [diff] [blame] | 373 | for frame in a_list: |
| 374 | if isinstance(frame, FrameSummary): |
| 375 | result.append(frame) |
| 376 | else: |
| 377 | filename, lineno, name, line = frame |
| 378 | result.append(FrameSummary(filename, lineno, name, line=line)) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 379 | return result |
| 380 | |
| 381 | def format(self): |
| 382 | """Format the stack ready for printing. |
| 383 | |
| 384 | Returns a list of strings ready for printing. Each string in the |
| 385 | resulting list corresponds to a single frame from the stack. |
| 386 | Each string ends in a newline; the strings may contain internal |
| 387 | newlines as well, for those items with source text lines. |
| 388 | """ |
| 389 | result = [] |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 390 | for frame in self: |
| 391 | row = [] |
| 392 | row.append(' File "{}", line {}, in {}\n'.format( |
| 393 | frame.filename, frame.lineno, frame.name)) |
| 394 | if frame.line: |
| 395 | row.append(' {}\n'.format(frame.line.strip())) |
| 396 | if frame.locals: |
| 397 | for name, value in sorted(frame.locals.items()): |
| 398 | row.append(' {name} = {value}\n'.format(name=name, value=value)) |
| 399 | result.append(''.join(row)) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 400 | return result |
| 401 | |
| 402 | |
| 403 | class TracebackException: |
| 404 | """An exception ready for rendering. |
| 405 | |
| 406 | The traceback module captures enough attributes from the original exception |
| 407 | to this intermediary form to ensure that no references are held, while |
| 408 | still being able to fully print or format it. |
| 409 | |
| 410 | Use `from_exception` to create TracebackException instances from exception |
| 411 | objects, or the constructor to create TracebackException instances from |
| 412 | individual components. |
| 413 | |
| 414 | - :attr:`__cause__` A TracebackException of the original *__cause__*. |
| 415 | - :attr:`__context__` A TracebackException of the original *__context__*. |
| 416 | - :attr:`__suppress_context__` The *__suppress_context__* value from the |
| 417 | original exception. |
| 418 | - :attr:`stack` A `StackSummary` representing the traceback. |
| 419 | - :attr:`exc_type` The class of the original traceback. |
| 420 | - :attr:`filename` For syntax errors - the filename where the error |
| 421 | occured. |
| 422 | - :attr:`lineno` For syntax errors - the linenumber where the error |
| 423 | occured. |
| 424 | - :attr:`text` For syntax errors - the text where the error |
| 425 | occured. |
| 426 | - :attr:`offset` For syntax errors - the offset into the text where the |
| 427 | error occured. |
| 428 | - :attr:`msg` For syntax errors - the compiler error message. |
| 429 | """ |
| 430 | |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 431 | def __init__(self, exc_type, exc_value, exc_traceback, *, limit=None, |
| 432 | lookup_lines=True, capture_locals=False, _seen=None): |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 433 | # NB: we need to accept exc_traceback, exc_value, exc_traceback to |
| 434 | # permit backwards compat with the existing API, otherwise we |
| 435 | # need stub thunk objects just to glue it together. |
| 436 | # Handle loops in __cause__ or __context__. |
| 437 | if _seen is None: |
| 438 | _seen = set() |
| 439 | _seen.add(exc_value) |
| 440 | # Gracefully handle (the way Python 2.4 and earlier did) the case of |
| 441 | # being called with no type or value (None, None, None). |
| 442 | if (exc_value and exc_value.__cause__ is not None |
| 443 | and exc_value.__cause__ not in _seen): |
| 444 | cause = TracebackException( |
| 445 | type(exc_value.__cause__), |
| 446 | exc_value.__cause__, |
| 447 | exc_value.__cause__.__traceback__, |
| 448 | limit=limit, |
| 449 | lookup_lines=False, |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 450 | capture_locals=capture_locals, |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 451 | _seen=_seen) |
| 452 | else: |
| 453 | cause = None |
| 454 | if (exc_value and exc_value.__context__ is not None |
| 455 | and exc_value.__context__ not in _seen): |
| 456 | context = TracebackException( |
| 457 | type(exc_value.__context__), |
| 458 | exc_value.__context__, |
| 459 | exc_value.__context__.__traceback__, |
| 460 | limit=limit, |
| 461 | lookup_lines=False, |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 462 | capture_locals=capture_locals, |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 463 | _seen=_seen) |
| 464 | else: |
| 465 | context = None |
Berker Peksag | c3f417d | 2015-07-24 17:36:21 +0300 | [diff] [blame] | 466 | self.exc_traceback = exc_traceback |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 467 | self.__cause__ = cause |
| 468 | self.__context__ = context |
| 469 | self.__suppress_context__ = \ |
| 470 | exc_value.__suppress_context__ if exc_value else False |
| 471 | # TODO: locals. |
| 472 | self.stack = StackSummary.extract( |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 473 | walk_tb(exc_traceback), limit=limit, lookup_lines=lookup_lines, |
| 474 | capture_locals=capture_locals) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 475 | self.exc_type = exc_type |
| 476 | # Capture now to permit freeing resources: only complication is in the |
| 477 | # unofficial API _format_final_exc_line |
| 478 | self._str = _some_str(exc_value) |
| 479 | if exc_type and issubclass(exc_type, SyntaxError): |
| 480 | # Handle SyntaxError's specially |
| 481 | self.filename = exc_value.filename |
| 482 | self.lineno = str(exc_value.lineno) |
| 483 | self.text = exc_value.text |
| 484 | self.offset = exc_value.offset |
| 485 | self.msg = exc_value.msg |
| 486 | if lookup_lines: |
| 487 | self._load_lines() |
| 488 | |
| 489 | @classmethod |
| 490 | def from_exception(self, exc, *args, **kwargs): |
| 491 | """Create a TracebackException from an exception.""" |
| 492 | return TracebackException( |
| 493 | type(exc), exc, exc.__traceback__, *args, **kwargs) |
| 494 | |
| 495 | def _load_lines(self): |
| 496 | """Private API. force all lines in the stack to be loaded.""" |
| 497 | for frame in self.stack: |
| 498 | frame.line |
| 499 | if self.__context__: |
| 500 | self.__context__._load_lines() |
| 501 | if self.__cause__: |
| 502 | self.__cause__._load_lines() |
| 503 | |
| 504 | def __eq__(self, other): |
| 505 | return self.__dict__ == other.__dict__ |
| 506 | |
| 507 | def __str__(self): |
| 508 | return self._str |
| 509 | |
| 510 | def format_exception_only(self): |
| 511 | """Format the exception part of the traceback. |
| 512 | |
| 513 | The return value is a generator of strings, each ending in a newline. |
| 514 | |
| 515 | Normally, the generator emits a single string; however, for |
| 516 | SyntaxError exceptions, it emites several lines that (when |
| 517 | printed) display detailed information about where the syntax |
| 518 | error occurred. |
| 519 | |
| 520 | The message indicating which exception occurred is always the last |
| 521 | string in the output. |
| 522 | """ |
| 523 | if self.exc_type is None: |
| 524 | yield _format_final_exc_line(None, self._str) |
| 525 | return |
| 526 | |
| 527 | stype = self.exc_type.__qualname__ |
| 528 | smod = self.exc_type.__module__ |
| 529 | if smod not in ("__main__", "builtins"): |
| 530 | stype = smod + '.' + stype |
| 531 | |
| 532 | if not issubclass(self.exc_type, SyntaxError): |
| 533 | yield _format_final_exc_line(stype, self._str) |
| 534 | return |
| 535 | |
| 536 | # It was a syntax error; show exactly where the problem was found. |
| 537 | filename = self.filename or "<string>" |
| 538 | lineno = str(self.lineno) or '?' |
| 539 | yield ' File "{}", line {}\n'.format(filename, lineno) |
| 540 | |
| 541 | badline = self.text |
| 542 | offset = self.offset |
| 543 | if badline is not None: |
| 544 | yield ' {}\n'.format(badline.strip()) |
| 545 | if offset is not None: |
| 546 | caretspace = badline.rstrip('\n') |
| 547 | offset = min(len(caretspace), offset) - 1 |
| 548 | caretspace = caretspace[:offset].lstrip() |
| 549 | # non-space whitespace (likes tabs) must be kept for alignment |
| 550 | caretspace = ((c.isspace() and c or ' ') for c in caretspace) |
| 551 | yield ' {}^\n'.format(''.join(caretspace)) |
| 552 | msg = self.msg or "<no detail available>" |
| 553 | yield "{}: {}\n".format(stype, msg) |
| 554 | |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 555 | def format(self, *, chain=True): |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 556 | """Format the exception. |
| 557 | |
| 558 | If chain is not *True*, *__cause__* and *__context__* will not be formatted. |
| 559 | |
| 560 | The return value is a generator of strings, each ending in a newline and |
| 561 | some containing internal newlines. `print_exception` is a wrapper around |
| 562 | this method which just prints the lines to a file. |
| 563 | |
| 564 | The message indicating which exception occurred is always the last |
| 565 | string in the output. |
| 566 | """ |
| 567 | if chain: |
| 568 | if self.__cause__ is not None: |
| 569 | yield from self.__cause__.format(chain=chain) |
| 570 | yield _cause_message |
| 571 | elif (self.__context__ is not None and |
| 572 | not self.__suppress_context__): |
| 573 | yield from self.__context__.format(chain=chain) |
| 574 | yield _context_message |
Berker Peksag | c3f417d | 2015-07-24 17:36:21 +0300 | [diff] [blame] | 575 | if self.exc_traceback is not None: |
| 576 | yield 'Traceback (most recent call last):\n' |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 577 | yield from self.stack.format() |
| 578 | yield from self.format_exception_only() |