Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`traceback` --- Print or retrieve a stack traceback |
| 2 | ======================================================== |
| 3 | |
| 4 | .. module:: traceback |
| 5 | :synopsis: Print or retrieve a stack traceback. |
| 6 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 7 | **Source code:** :source:`Lib/traceback.py` |
| 8 | |
| 9 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
| 11 | This module provides a standard interface to extract, format and print stack |
| 12 | traces of Python programs. It exactly mimics the behavior of the Python |
| 13 | interpreter when it prints a stack trace. This is useful when you want to print |
| 14 | stack traces under program control, such as in a "wrapper" around the |
| 15 | interpreter. |
| 16 | |
| 17 | .. index:: object: traceback |
| 18 | |
| 19 | The module uses traceback objects --- this is the object type that is stored in |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 20 | the :data:`sys.last_traceback` variable and returned as the third item from |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | :func:`sys.exc_info`. |
| 22 | |
| 23 | The module defines the following functions: |
| 24 | |
| 25 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 26 | .. function:: print_tb(tb, limit=None, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 28 | Print up to *limit* stack trace entries from traceback object *tb* (starting |
| 29 | from the caller's frame) if *limit* is positive. Otherwise, print the last |
| 30 | ``abs(limit)`` entries. If *limit* is omitted or ``None``, all entries are |
| 31 | printed. If *file* is omitted or ``None``, the output goes to |
| 32 | ``sys.stderr``; otherwise it should be an open file or file-like object to |
| 33 | receive the output. |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 34 | |
| 35 | .. versionchanged:: 3.5 |
| 36 | Added negative *limit* support. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
| 38 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 39 | .. function:: print_exception(etype, value, tb, limit=None, file=None, chain=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 40 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 41 | Print exception information and stack trace entries from traceback object |
| 42 | *tb* to *file*. This differs from :func:`print_tb` in the following |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 43 | ways: |
| 44 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 45 | * if *tb* is not ``None``, it prints a header ``Traceback (most recent |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 46 | call last):`` |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 47 | * it prints the exception *etype* and *value* after the stack trace |
| 48 | * if *etype* is :exc:`SyntaxError` and *value* has the appropriate format, it |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 49 | prints the line where the syntax error occurred with a caret indicating the |
| 50 | approximate position of the error. |
| 51 | |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 52 | The optional *limit* argument has the same meaning as for :func:`print_tb`. |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 53 | If *chain* is true (the default), then chained exceptions (the |
| 54 | :attr:`__cause__` or :attr:`__context__` attributes of the exception) will be |
| 55 | printed as well, like the interpreter itself does when printing an unhandled |
| 56 | exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 59 | .. function:: print_exc(limit=None, file=None, chain=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 61 | This is a shorthand for ``print_exception(*sys.exc_info(), limit, file, |
| 62 | chain)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
| 64 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 65 | .. function:: print_last(limit=None, file=None, chain=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 66 | |
| 67 | This is a shorthand for ``print_exception(sys.last_type, sys.last_value, |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 68 | sys.last_traceback, limit, file, chain)``. In general it will work only |
| 69 | after an exception has reached an interactive prompt (see |
| 70 | :data:`sys.last_type`). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
| 72 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 73 | .. function:: print_stack(f=None, limit=None, file=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 75 | Print up to *limit* stack trace entries (starting from the invocation |
| 76 | point) if *limit* is positive. Otherwise, print the last ``abs(limit)`` |
| 77 | entries. If *limit* is omitted or ``None``, all entries are printed. |
| 78 | The optional *f* argument can be used to specify an alternate stack frame |
| 79 | to start. The optional *file* argument has the same meaning as for |
| 80 | :func:`print_tb`. |
| 81 | |
| 82 | .. versionchanged:: 3.5 |
| 83 | Added negative *limit* support. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 86 | .. function:: extract_tb(tb, limit=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 88 | Return a list of "pre-processed" stack trace entries extracted from the |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 89 | traceback object *tb*. It is useful for alternate formatting of |
Serhiy Storchaka | 24559e4 | 2015-05-03 13:19:46 +0300 | [diff] [blame] | 90 | stack traces. The optional *limit* argument has the same meaning as for |
| 91 | :func:`print_tb`. A "pre-processed" stack trace entry is a 4-tuple |
| 92 | (*filename*, *line number*, *function name*, *text*) representing the |
| 93 | information that is usually printed for a stack trace. The *text* is a |
| 94 | string with leading and trailing whitespace stripped; if the source is |
| 95 | not available it is ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
| 97 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 98 | .. function:: extract_stack(f=None, limit=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
| 100 | Extract the raw traceback from the current stack frame. The return value has |
| 101 | the same format as for :func:`extract_tb`. The optional *f* and *limit* |
| 102 | arguments have the same meaning as for :func:`print_stack`. |
| 103 | |
| 104 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 105 | .. function:: format_list(extracted_list) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
| 107 | Given a list of tuples as returned by :func:`extract_tb` or |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 108 | :func:`extract_stack`, return a list of strings ready for printing. Each |
| 109 | string in the resulting list corresponds to the item with the same index in |
| 110 | the argument list. Each string ends in a newline; the strings may contain |
| 111 | internal newlines as well, for those items whose source text line is not |
| 112 | ``None``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
| 114 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 115 | .. function:: format_exception_only(etype, value) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 117 | Format the exception part of a traceback. The arguments are the exception |
| 118 | type and value such as given by ``sys.last_type`` and ``sys.last_value``. |
| 119 | The return value is a list of strings, each ending in a newline. Normally, |
| 120 | the list contains a single string; however, for :exc:`SyntaxError` |
| 121 | exceptions, it contains several lines that (when printed) display detailed |
| 122 | information about where the syntax error occurred. The message indicating |
| 123 | which exception occurred is the always last string in the list. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
| 125 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 126 | .. function:: format_exception(etype, value, tb, limit=None, chain=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
| 128 | Format a stack trace and the exception information. The arguments have the |
| 129 | same meaning as the corresponding arguments to :func:`print_exception`. The |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 130 | return value is a list of strings, each ending in a newline and some |
| 131 | containing internal newlines. When these lines are concatenated and printed, |
| 132 | exactly the same text is printed as does :func:`print_exception`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 133 | |
| 134 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 135 | .. function:: format_exc(limit=None, chain=True) |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 136 | |
Senthil Kumaran | a82908f | 2016-01-15 21:45:17 -0800 | [diff] [blame] | 137 | This is like ``print_exc(limit)`` but returns a string instead of printing to |
| 138 | a file. |
Georg Brandl | 1aea30a | 2008-07-19 15:51:07 +0000 | [diff] [blame] | 139 | |
| 140 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 141 | .. function:: format_tb(tb, limit=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | |
| 143 | A shorthand for ``format_list(extract_tb(tb, limit))``. |
| 144 | |
| 145 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 146 | .. function:: format_stack(f=None, limit=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | |
| 148 | A shorthand for ``format_list(extract_stack(f, limit))``. |
| 149 | |
Andrew Kuchling | 173a157 | 2013-09-15 18:15:56 -0400 | [diff] [blame] | 150 | .. function:: clear_frames(tb) |
| 151 | |
| 152 | Clears the local variables of all the stack frames in a traceback *tb* |
| 153 | by calling the :meth:`clear` method of each frame object. |
| 154 | |
| 155 | .. versionadded:: 3.4 |
| 156 | |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 157 | .. function:: walk_stack(f) |
| 158 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 159 | Walk a stack following ``f.f_back`` from the given frame, yielding the frame |
| 160 | and line number for each frame. If *f* is ``None``, the current stack is |
| 161 | used. This helper is used with :meth:`StackSummary.extract`. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 162 | |
| 163 | .. versionadded:: 3.5 |
| 164 | |
| 165 | .. function:: walk_tb(tb) |
| 166 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 167 | Walk a traceback following ``tb_next`` yielding the frame and line number |
| 168 | for each frame. This helper is used with :meth:`StackSummary.extract`. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 169 | |
| 170 | .. versionadded:: 3.5 |
| 171 | |
| 172 | The module also defines the following classes: |
| 173 | |
| 174 | :class:`TracebackException` Objects |
| 175 | ----------------------------------- |
| 176 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 177 | .. versionadded:: 3.5 |
| 178 | |
| 179 | :class:`TracebackException` objects are created from actual exceptions to |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 180 | capture data for later printing in a lightweight fashion. |
| 181 | |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 182 | .. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 183 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 184 | Capture an exception for later rendering. *limit*, *lookup_lines* and |
| 185 | *capture_locals* are as for the :class:`StackSummary` class. |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 186 | |
| 187 | Note that when locals are captured, they are also shown in the traceback. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 188 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 189 | .. attribute:: __cause__ |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 190 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 191 | A :class:`TracebackException` of the original ``__cause__``. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 192 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 193 | .. attribute:: __context__ |
Robert Collins | d7c7e0e | 2015-03-05 20:28:52 +1300 | [diff] [blame] | 194 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 195 | A :class:`TracebackException` of the original ``__context__``. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 196 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 197 | .. attribute:: __suppress_context__ |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 198 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 199 | The ``__suppress_context__`` value from the original exception. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 200 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 201 | .. attribute:: stack |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 202 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 203 | A :class:`StackSummary` representing the traceback. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 204 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 205 | .. attribute:: exc_type |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 206 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 207 | The class of the original traceback. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 208 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 209 | .. attribute:: filename |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 210 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 211 | For syntax errors - the file name where the error occurred. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 212 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 213 | .. attribute:: lineno |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 214 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 215 | For syntax errors - the line number where the error occurred. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 216 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 217 | .. attribute:: text |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 218 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 219 | For syntax errors - the text where the error occurred. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 220 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 221 | .. attribute:: offset |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 222 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 223 | For syntax errors - the offset into the text where the error occurred. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 224 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 225 | .. attribute:: msg |
| 226 | |
| 227 | For syntax errors - the compiler error message. |
| 228 | |
| 229 | .. classmethod:: from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False) |
| 230 | |
| 231 | Capture an exception for later rendering. *limit*, *lookup_lines* and |
| 232 | *capture_locals* are as for the :class:`StackSummary` class. |
| 233 | |
| 234 | Note that when locals are captured, they are also shown in the traceback. |
| 235 | |
| 236 | .. method:: format(*, chain=True) |
| 237 | |
| 238 | Format the exception. |
| 239 | |
| 240 | If *chain* is not ``True``, ``__cause__`` and ``__context__`` will not |
| 241 | be formatted. |
| 242 | |
| 243 | The return value is a generator of strings, each ending in a newline and |
| 244 | some containing internal newlines. :func:`~traceback.print_exception` |
| 245 | is a wrapper around this method which just prints the lines to a file. |
| 246 | |
| 247 | The message indicating which exception occurred is always the last |
| 248 | string in the output. |
| 249 | |
| 250 | .. method:: format_exception_only() |
| 251 | |
| 252 | Format the exception part of the traceback. |
| 253 | |
| 254 | The return value is a generator of strings, each ending in a newline. |
| 255 | |
| 256 | Normally, the generator emits a single string; however, for |
| 257 | :exc:`SyntaxError` exceptions, it emits several lines that (when |
| 258 | printed) display detailed information about where the syntax |
| 259 | error occurred. |
| 260 | |
| 261 | The message indicating which exception occurred is always the last |
| 262 | string in the output. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 263 | |
| 264 | |
| 265 | :class:`StackSummary` Objects |
| 266 | ----------------------------- |
| 267 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 268 | .. versionadded:: 3.5 |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 269 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 270 | :class:`StackSummary` objects represent a call stack ready for formatting. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 271 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 272 | .. class:: StackSummary |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 273 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 274 | .. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 275 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 276 | Construct a :class:`StackSummary` object from a frame generator (such as |
| 277 | is returned by :func:`~traceback.walk_stack` or |
| 278 | :func:`~traceback.walk_tb`). |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 279 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 280 | If *limit* is supplied, only this many frames are taken from *frame_gen*. |
| 281 | If *lookup_lines* is ``False``, the returned :class:`FrameSummary` |
| 282 | objects will not have read their lines in yet, making the cost of |
| 283 | creating the :class:`StackSummary` cheaper (which may be valuable if it |
| 284 | may not actually get formatted). If *capture_locals* is ``True`` the |
| 285 | local variables in each :class:`FrameSummary` are captured as object |
| 286 | representations. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 287 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 288 | .. classmethod:: from_list(a_list) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 289 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 290 | Construct a :class:`StackSummary` object from a supplied old-style list |
| 291 | of tuples. Each tuple should be a 4-tuple with filename, lineno, name, |
| 292 | line as the elements. |
| 293 | |
Nick Coghlan | d003423 | 2016-08-15 13:11:34 +1000 | [diff] [blame] | 294 | .. method:: format() |
| 295 | |
| 296 | Returns a list of strings ready for printing. Each string in the |
| 297 | resulting list corresponds to a single frame from the stack. |
| 298 | Each string ends in a newline; the strings may contain internal |
| 299 | newlines as well, for those items with source text lines. |
| 300 | |
| 301 | For long sequences of the same frame and line, the first few |
| 302 | repetitions are shown, followed by a summary line stating the exact |
| 303 | number of further repetitions. |
| 304 | |
Nick Coghlan | 02d03df | 2016-08-16 10:58:14 +1000 | [diff] [blame] | 305 | .. versionchanged:: 3.6 |
| 306 | Long sequences of repeated frames are now abbreviated. |
Nick Coghlan | d003423 | 2016-08-15 13:11:34 +1000 | [diff] [blame] | 307 | |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 308 | |
| 309 | :class:`FrameSummary` Objects |
| 310 | ----------------------------- |
| 311 | |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 312 | .. versionadded:: 3.5 |
| 313 | |
| 314 | :class:`FrameSummary` objects represent a single frame in a traceback. |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 315 | |
| 316 | .. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None) |
Robert Collins | 6bc2c1e | 2015-03-05 12:07:57 +1300 | [diff] [blame] | 317 | |
| 318 | Represent a single frame in the traceback or stack that is being formatted |
| 319 | or printed. It may optionally have a stringified version of the frames |
Berker Peksag | 49f373b | 2015-03-06 12:18:06 +0200 | [diff] [blame] | 320 | locals included in it. If *lookup_line* is ``False``, the source code is not |
| 321 | looked up until the :class:`FrameSummary` has the :attr:`~FrameSummary.line` |
| 322 | attribute accessed (which also happens when casting it to a tuple). |
| 323 | :attr:`~FrameSummary.line` may be directly provided, and will prevent line |
| 324 | lookups happening at all. *locals* is an optional local variable |
| 325 | dictionary, and if supplied the variable representations are stored in the |
| 326 | summary for later display. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 327 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 328 | .. _traceback-example: |
| 329 | |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 330 | Traceback Examples |
| 331 | ------------------ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 332 | |
| 333 | This simple example implements a basic read-eval-print loop, similar to (but |
| 334 | less useful than) the standard Python interactive interpreter loop. For a more |
| 335 | complete implementation of the interpreter loop, refer to the :mod:`code` |
| 336 | module. :: |
| 337 | |
| 338 | import sys, traceback |
| 339 | |
| 340 | def run_user_code(envdir): |
Georg Brandl | 8d5c392 | 2007-12-02 22:48:17 +0000 | [diff] [blame] | 341 | source = input(">>> ") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 342 | try: |
| 343 | exec(source, envdir) |
Andrew Svetlov | 4739561 | 2012-11-02 22:07:26 +0200 | [diff] [blame] | 344 | except Exception: |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 345 | print("Exception in user code:") |
| 346 | print("-"*60) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 347 | traceback.print_exc(file=sys.stdout) |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 348 | print("-"*60) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 349 | |
| 350 | envdir = {} |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 351 | while True: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 352 | run_user_code(envdir) |
| 353 | |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 354 | |
| 355 | The following example demonstrates the different ways to print and format the |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 356 | exception and traceback: |
| 357 | |
| 358 | .. testcode:: |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 359 | |
| 360 | import sys, traceback |
| 361 | |
| 362 | def lumberjack(): |
| 363 | bright_side_of_death() |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 364 | |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 365 | def bright_side_of_death(): |
| 366 | return tuple()[0] |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 367 | |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 368 | try: |
| 369 | lumberjack() |
Ezio Melotti | 5e0110e | 2010-03-13 01:28:34 +0000 | [diff] [blame] | 370 | except IndexError: |
| 371 | exc_type, exc_value, exc_traceback = sys.exc_info() |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 372 | print("*** print_tb:") |
Ezio Melotti | 5e0110e | 2010-03-13 01:28:34 +0000 | [diff] [blame] | 373 | traceback.print_tb(exc_traceback, limit=1, file=sys.stdout) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 374 | print("*** print_exception:") |
Ezio Melotti | 5e0110e | 2010-03-13 01:28:34 +0000 | [diff] [blame] | 375 | traceback.print_exception(exc_type, exc_value, exc_traceback, |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 376 | limit=2, file=sys.stdout) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 377 | print("*** print_exc:") |
Zachary Ware | c90fccd | 2016-08-10 00:35:27 -0500 | [diff] [blame] | 378 | traceback.print_exc(limit=2, file=sys.stdout) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 379 | print("*** format_exc, first and last line:") |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 380 | formatted_lines = traceback.format_exc().splitlines() |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 381 | print(formatted_lines[0]) |
| 382 | print(formatted_lines[-1]) |
| 383 | print("*** format_exception:") |
Ezio Melotti | 5e0110e | 2010-03-13 01:28:34 +0000 | [diff] [blame] | 384 | print(repr(traceback.format_exception(exc_type, exc_value, |
| 385 | exc_traceback))) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 386 | print("*** extract_tb:") |
Ezio Melotti | 5e0110e | 2010-03-13 01:28:34 +0000 | [diff] [blame] | 387 | print(repr(traceback.extract_tb(exc_traceback))) |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 388 | print("*** format_tb:") |
Ezio Melotti | 5e0110e | 2010-03-13 01:28:34 +0000 | [diff] [blame] | 389 | print(repr(traceback.format_tb(exc_traceback))) |
| 390 | print("*** tb_lineno:", exc_traceback.tb_lineno) |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 391 | |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 392 | The output for the example would look similar to this: |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 393 | |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 394 | .. testoutput:: |
| 395 | :options: +NORMALIZE_WHITESPACE |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 396 | |
| 397 | *** print_tb: |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 398 | File "<doctest...>", line 10, in <module> |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 399 | lumberjack() |
| 400 | *** print_exception: |
| 401 | Traceback (most recent call last): |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 402 | File "<doctest...>", line 10, in <module> |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 403 | lumberjack() |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 404 | File "<doctest...>", line 4, in lumberjack |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 405 | bright_side_of_death() |
| 406 | IndexError: tuple index out of range |
| 407 | *** print_exc: |
| 408 | Traceback (most recent call last): |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 409 | File "<doctest...>", line 10, in <module> |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 410 | lumberjack() |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 411 | File "<doctest...>", line 4, in lumberjack |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 412 | bright_side_of_death() |
| 413 | IndexError: tuple index out of range |
| 414 | *** format_exc, first and last line: |
| 415 | Traceback (most recent call last): |
| 416 | IndexError: tuple index out of range |
| 417 | *** format_exception: |
| 418 | ['Traceback (most recent call last):\n', |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 419 | ' File "<doctest...>", line 10, in <module>\n lumberjack()\n', |
| 420 | ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n', |
| 421 | ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n', |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 422 | 'IndexError: tuple index out of range\n'] |
| 423 | *** extract_tb: |
Zachary Ware | c90fccd | 2016-08-10 00:35:27 -0500 | [diff] [blame] | 424 | [<FrameSummary file <doctest...>, line 10 in <module>>, |
| 425 | <FrameSummary file <doctest...>, line 4 in lumberjack>, |
| 426 | <FrameSummary file <doctest...>, line 7 in bright_side_of_death>] |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 427 | *** format_tb: |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 428 | [' File "<doctest...>", line 10, in <module>\n lumberjack()\n', |
| 429 | ' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n', |
| 430 | ' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n'] |
| 431 | *** tb_lineno: 10 |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 432 | |
| 433 | |
| 434 | The following example shows the different ways to print and format the stack:: |
| 435 | |
| 436 | >>> import traceback |
| 437 | >>> def another_function(): |
| 438 | ... lumberstack() |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 439 | ... |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 440 | >>> def lumberstack(): |
| 441 | ... traceback.print_stack() |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 442 | ... print(repr(traceback.extract_stack())) |
| 443 | ... print(repr(traceback.format_stack())) |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 444 | ... |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 445 | >>> another_function() |
| 446 | File "<doctest>", line 10, in <module> |
| 447 | another_function() |
| 448 | File "<doctest>", line 3, in another_function |
| 449 | lumberstack() |
| 450 | File "<doctest>", line 6, in lumberstack |
| 451 | traceback.print_stack() |
| 452 | [('<doctest>', 10, '<module>', 'another_function()'), |
| 453 | ('<doctest>', 3, 'another_function', 'lumberstack()'), |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 454 | ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')] |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 455 | [' File "<doctest>", line 10, in <module>\n another_function()\n', |
| 456 | ' File "<doctest>", line 3, in another_function\n lumberstack()\n', |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 457 | ' File "<doctest>", line 8, in lumberstack\n print(repr(traceback.format_stack()))\n'] |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 458 | |
| 459 | |
R. David Murray | e02a301 | 2009-04-27 18:38:19 +0000 | [diff] [blame] | 460 | This last example demonstrates the final few formatting functions: |
| 461 | |
| 462 | .. doctest:: |
| 463 | :options: +NORMALIZE_WHITESPACE |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 464 | |
| 465 | >>> import traceback |
Georg Brandl | 0142d4a | 2009-04-27 16:22:44 +0000 | [diff] [blame] | 466 | >>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'), |
| 467 | ... ('eggs.py', 42, 'eggs', 'return "bacon"')]) |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 468 | [' File "spam.py", line 3, in <module>\n spam.eggs()\n', |
| 469 | ' File "eggs.py", line 42, in eggs\n return "bacon"\n'] |
Georg Brandl | 0142d4a | 2009-04-27 16:22:44 +0000 | [diff] [blame] | 470 | >>> an_error = IndexError('tuple index out of range') |
| 471 | >>> traceback.format_exception_only(type(an_error), an_error) |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 472 | ['IndexError: tuple index out of range\n'] |