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