path: root/devdocs/python~3.12/library%2Ftraceback.html

 <span id="traceback-print-or-retrieve-a-stack-traceback"></span><h1>traceback — Print or retrieve a stack traceback</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/traceback.py">Lib/traceback.py</a></p>  <p>This module provides a standard interface to extract, format and print stack traces of Python programs. It exactly mimics the behavior of the Python interpreter when it prints a stack trace. This is useful when you want to print stack traces under program control, such as in a “wrapper” around the interpreter.</p> <p id="index-0">The module uses <a class="reference internal" href="../reference/datamodel#traceback-objects"><span class="std std-ref">traceback objects</span></a> — these are objects of type <a class="reference internal" href="types#types.TracebackType" title="types.TracebackType"><code>types.TracebackType</code></a>, which are assigned to the <a class="reference internal" href="exceptions#BaseException.__traceback__" title="BaseException.__traceback__"><code>__traceback__</code></a> field of <a class="reference internal" href="exceptions#BaseException" title="BaseException"><code>BaseException</code></a> instances.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
<code>Module</code> <a class="reference internal" href="faulthandler#module-faulthandler" title="faulthandler: Dump the Python traceback."><code>faulthandler</code></a>
</dt>
<dd>
<p>Used to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal.</p> </dd> <dt>
<code>Module</code> <a class="reference internal" href="pdb#module-pdb" title="pdb: The Python debugger for interactive interpreters."><code>pdb</code></a>
</dt>
<dd>
<p>Interactive source code debugger for Python programs.</p> </dd> </dl> </div> <p>The module defines the following functions:</p> <dl class="py function"> <dt class="sig sig-object py" id="traceback.print_tb">
<code>traceback.print_tb(tb, limit=None, file=None)</code> </dt> <dd>
<p>Print up to <em>limit</em> stack trace entries from <a class="reference internal" href="../reference/datamodel#traceback-objects"><span class="std std-ref">traceback object</span></a> <em>tb</em> (starting from the caller’s frame) if <em>limit</em> is positive. Otherwise, print the last <code>abs(limit)</code> entries. If <em>limit</em> is omitted or <code>None</code>, all entries are printed. If <em>file</em> is omitted or <code>None</code>, the output goes to <a class="reference internal" href="sys#sys.stderr" title="sys.stderr"><code>sys.stderr</code></a>; otherwise it should be an open <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file</span></a> or <a class="reference internal" href="../glossary#term-file-like-object"><span class="xref std std-term">file-like object</span></a> to receive the output.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Added negative <em>limit</em> support.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.print_exception">
<code>traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)</code> </dt> <dd>
<p>Print exception information and stack trace entries from <a class="reference internal" href="../reference/datamodel#traceback-objects"><span class="std std-ref">traceback object</span></a> <em>tb</em> to <em>file</em>. This differs from <a class="reference internal" href="#traceback.print_tb" title="traceback.print_tb"><code>print_tb()</code></a> in the following ways:</p> <ul class="simple"> <li>if <em>tb</em> is not <code>None</code>, it prints a header <code>Traceback (most recent
call last):</code>
</li> <li>it prints the exception type and <em>value</em> after the stack trace</li> </ul> <ul class="simple" id="index-1"> <li>if <em>type(value)</em> is <a class="reference internal" href="exceptions#SyntaxError" title="SyntaxError"><code>SyntaxError</code></a> and <em>value</em> has the appropriate format, it prints the line where the syntax error occurred with a caret indicating the approximate position of the error.</li> </ul> <p>Since Python 3.10, instead of passing <em>value</em> and <em>tb</em>, an exception object can be passed as the first argument. If <em>value</em> and <em>tb</em> are provided, the first argument is ignored in order to provide backwards compatibility.</p> <p>The optional <em>limit</em> argument has the same meaning as for <a class="reference internal" href="#traceback.print_tb" title="traceback.print_tb"><code>print_tb()</code></a>. If <em>chain</em> is true (the default), then chained exceptions (the <a class="reference internal" href="exceptions#BaseException.__cause__" title="BaseException.__cause__"><code>__cause__</code></a> or <a class="reference internal" href="exceptions#BaseException.__context__" title="BaseException.__context__"><code>__context__</code></a> attributes of the exception) will be printed as well, like the interpreter itself does when printing an unhandled exception.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>etype</em> argument is ignored and inferred from the type of <em>value</em>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>The <em>etype</em> parameter has been renamed to <em>exc</em> and is now positional-only.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.print_exc">
<code>traceback.print_exc(limit=None, file=None, chain=True)</code> </dt> <dd>
<p>This is a shorthand for <code>print_exception(sys.exception(), limit, file,
chain)</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.print_last">
<code>traceback.print_last(limit=None, file=None, chain=True)</code> </dt> <dd>
<p>This is a shorthand for <code>print_exception(sys.last_exc, limit, file,
chain)</code>. In general it will work only after an exception has reached an interactive prompt (see <a class="reference internal" href="sys#sys.last_exc" title="sys.last_exc"><code>sys.last_exc</code></a>).</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.print_stack">
<code>traceback.print_stack(f=None, limit=None, file=None)</code> </dt> <dd>
<p>Print up to <em>limit</em> stack trace entries (starting from the invocation point) if <em>limit</em> is positive. Otherwise, print the last <code>abs(limit)</code> entries. If <em>limit</em> is omitted or <code>None</code>, all entries are printed. The optional <em>f</em> argument can be used to specify an alternate <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">stack frame</span></a> to start. The optional <em>file</em> argument has the same meaning as for <a class="reference internal" href="#traceback.print_tb" title="traceback.print_tb"><code>print_tb()</code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Added negative <em>limit</em> support.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.extract_tb">
<code>traceback.extract_tb(tb, limit=None)</code> </dt> <dd>
<p>Return a <a class="reference internal" href="#traceback.StackSummary" title="traceback.StackSummary"><code>StackSummary</code></a> object representing a list of “pre-processed” stack trace entries extracted from the <a class="reference internal" href="../reference/datamodel#traceback-objects"><span class="std std-ref">traceback object</span></a> <em>tb</em>. It is useful for alternate formatting of stack traces. The optional <em>limit</em> argument has the same meaning as for <a class="reference internal" href="#traceback.print_tb" title="traceback.print_tb"><code>print_tb()</code></a>. A “pre-processed” stack trace entry is a <a class="reference internal" href="#traceback.FrameSummary" title="traceback.FrameSummary"><code>FrameSummary</code></a> object containing attributes <a class="reference internal" href="#traceback.FrameSummary.filename" title="traceback.FrameSummary.filename"><code>filename</code></a>, <a class="reference internal" href="#traceback.FrameSummary.lineno" title="traceback.FrameSummary.lineno"><code>lineno</code></a>, <a class="reference internal" href="#traceback.FrameSummary.name" title="traceback.FrameSummary.name"><code>name</code></a>, and <a class="reference internal" href="#traceback.FrameSummary.line" title="traceback.FrameSummary.line"><code>line</code></a> representing the information that is usually printed for a stack trace.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.extract_stack">
<code>traceback.extract_stack(f=None, limit=None)</code> </dt> <dd>
<p>Extract the raw traceback from the current <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">stack frame</span></a>. The return value has the same format as for <a class="reference internal" href="#traceback.extract_tb" title="traceback.extract_tb"><code>extract_tb()</code></a>. The optional <em>f</em> and <em>limit</em> arguments have the same meaning as for <a class="reference internal" href="#traceback.print_stack" title="traceback.print_stack"><code>print_stack()</code></a>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.format_list">
<code>traceback.format_list(extracted_list)</code> </dt> <dd>
<p>Given a list of tuples or <a class="reference internal" href="#traceback.FrameSummary" title="traceback.FrameSummary"><code>FrameSummary</code></a> objects as returned by <a class="reference internal" href="#traceback.extract_tb" title="traceback.extract_tb"><code>extract_tb()</code></a> or <a class="reference internal" href="#traceback.extract_stack" title="traceback.extract_stack"><code>extract_stack()</code></a>, return a list of strings ready for printing. Each string in the resulting list corresponds to the item with the same index in the argument list. Each string ends in a newline; the strings may contain internal newlines as well, for those items whose source text line is not <code>None</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.format_exception_only">
<code>traceback.format_exception_only(exc, /[, value])</code> </dt> <dd>
<p>Format the exception part of a traceback using an exception value such as given by <a class="reference internal" href="sys#sys.last_value" title="sys.last_value"><code>sys.last_value</code></a>. The return value is a list of strings, each ending in a newline. The list contains the exception’s message, which is normally a single string; however, for <a class="reference internal" href="exceptions#SyntaxError" title="SyntaxError"><code>SyntaxError</code></a> exceptions, it contains several lines that (when printed) display detailed information about where the syntax error occurred. Following the message, the list contains the exception’s <a class="reference internal" href="exceptions#BaseException.__notes__" title="BaseException.__notes__"><code>notes</code></a>.</p> <p>Since Python 3.10, instead of passing <em>value</em>, an exception object can be passed as the first argument. If <em>value</em> is provided, the first argument is ignored in order to provide backwards compatibility.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>The <em>etype</em> parameter has been renamed to <em>exc</em> and is now positional-only.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>The returned list now includes any <a class="reference internal" href="exceptions#BaseException.__notes__" title="BaseException.__notes__"><code>notes</code></a> attached to the exception.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.format_exception">
<code>traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)</code> </dt> <dd>
<p>Format a stack trace and the exception information. The arguments have the same meaning as the corresponding arguments to <a class="reference internal" href="#traceback.print_exception" title="traceback.print_exception"><code>print_exception()</code></a>. The return value is a list of strings, each ending in a newline and some containing internal newlines. When these lines are concatenated and printed, exactly the same text is printed as does <a class="reference internal" href="#traceback.print_exception" title="traceback.print_exception"><code>print_exception()</code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>etype</em> argument is ignored and inferred from the type of <em>value</em>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>This function’s behavior and signature were modified to match <a class="reference internal" href="#traceback.print_exception" title="traceback.print_exception"><code>print_exception()</code></a>.</p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.format_exc">
<code>traceback.format_exc(limit=None, chain=True)</code> </dt> <dd>
<p>This is like <code>print_exc(limit)</code> but returns a string instead of printing to a file.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.format_tb">
<code>traceback.format_tb(tb, limit=None)</code> </dt> <dd>
<p>A shorthand for <code>format_list(extract_tb(tb, limit))</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.format_stack">
<code>traceback.format_stack(f=None, limit=None)</code> </dt> <dd>
<p>A shorthand for <code>format_list(extract_stack(f, limit))</code>.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.clear_frames">
<code>traceback.clear_frames(tb)</code> </dt> <dd>
<p>Clears the local variables of all the stack frames in a <a class="reference internal" href="../reference/datamodel#traceback-objects"><span class="std std-ref">traceback</span></a> <em>tb</em> by calling the <a class="reference internal" href="../reference/datamodel#frame.clear" title="frame.clear"><code>clear()</code></a> method of each <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">frame object</span></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.walk_stack">
<code>traceback.walk_stack(f)</code> </dt> <dd>
<p>Walk a stack following <a class="reference internal" href="../reference/datamodel#frame.f_back" title="frame.f_back"><code>f.f_back</code></a> from the given frame, yielding the frame and line number for each frame. If <em>f</em> is <code>None</code>, the current stack is used. This helper is used with <a class="reference internal" href="#traceback.StackSummary.extract" title="traceback.StackSummary.extract"><code>StackSummary.extract()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="traceback.walk_tb">
<code>traceback.walk_tb(tb)</code> </dt> <dd>
<p>Walk a traceback following <a class="reference internal" href="../reference/datamodel#traceback.tb_next" title="traceback.tb_next"><code>tb_next</code></a> yielding the frame and line number for each frame. This helper is used with <a class="reference internal" href="#traceback.StackSummary.extract" title="traceback.StackSummary.extract"><code>StackSummary.extract()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> </dd>
</dl> <p>The module also defines the following classes:</p> <section id="tracebackexception-objects"> <h2>
<code>TracebackException</code> Objects</h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> <p><code>TracebackException</code> objects are created from actual exceptions to capture data for later printing in a lightweight fashion.</p> <dl class="py class"> <dt class="sig sig-object py" id="traceback.TracebackException">
<code>class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)</code> </dt> <dd>
<p>Capture an exception for later rendering. <em>limit</em>, <em>lookup_lines</em> and <em>capture_locals</em> are as for the <a class="reference internal" href="#traceback.StackSummary" title="traceback.StackSummary"><code>StackSummary</code></a> class.</p> <p>If <em>compact</em> is true, only data that is required by <code>TracebackException</code>’s <a class="reference internal" href="functions#format" title="format"><code>format()</code></a> method is saved in the class attributes. In particular, the <a class="reference internal" href="#traceback.TracebackException.__context__" title="traceback.TracebackException.__context__"><code>__context__</code></a> field is calculated only if <a class="reference internal" href="#traceback.TracebackException.__cause__" title="traceback.TracebackException.__cause__"><code>__cause__</code></a> is <code>None</code> and <a class="reference internal" href="#traceback.TracebackException.__suppress_context__" title="traceback.TracebackException.__suppress_context__"><code>__suppress_context__</code></a> is false.</p> <p>Note that when locals are captured, they are also shown in the traceback.</p> <p><em>max_group_width</em> and <em>max_group_depth</em> control the formatting of exception groups (see <a class="reference internal" href="exceptions#BaseExceptionGroup" title="BaseExceptionGroup"><code>BaseExceptionGroup</code></a>). The depth refers to the nesting level of the group, and the width refers to the size of a single exception group’s exceptions array. The formatted output is truncated when either limit is exceeded.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>Added the <em>compact</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>Added the <em>max_group_width</em> and <em>max_group_depth</em> parameters.</p> </div> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.__cause__">
<code>__cause__</code> </dt> <dd>
<p>A <code>TracebackException</code> of the original <a class="reference internal" href="exceptions#BaseException.__cause__" title="BaseException.__cause__"><code>__cause__</code></a>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.__context__">
<code>__context__</code> </dt> <dd>
<p>A <code>TracebackException</code> of the original <a class="reference internal" href="exceptions#BaseException.__context__" title="BaseException.__context__"><code>__context__</code></a>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.exceptions">
<code>exceptions</code> </dt> <dd>
<p>If <code>self</code> represents an <a class="reference internal" href="exceptions#ExceptionGroup" title="ExceptionGroup"><code>ExceptionGroup</code></a>, this field holds a list of <code>TracebackException</code> instances representing the nested exceptions. Otherwise it is <code>None</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.__suppress_context__">
<code>__suppress_context__</code> </dt> <dd>
<p>The <a class="reference internal" href="exceptions#BaseException.__suppress_context__" title="BaseException.__suppress_context__"><code>__suppress_context__</code></a> value from the original exception.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.__notes__">
<code>__notes__</code> </dt> <dd>
<p>The <a class="reference internal" href="exceptions#BaseException.__notes__" title="BaseException.__notes__"><code>__notes__</code></a> value from the original exception, or <code>None</code> if the exception does not have any notes. If it is not <code>None</code> is it formatted in the traceback after the exception string.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.stack">
<code>stack</code> </dt> <dd>
<p>A <a class="reference internal" href="#traceback.StackSummary" title="traceback.StackSummary"><code>StackSummary</code></a> representing the traceback.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.exc_type">
<code>exc_type</code> </dt> <dd>
<p>The class of the original traceback.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.filename">
<code>filename</code> </dt> <dd>
<p>For syntax errors - the file name where the error occurred.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.lineno">
<code>lineno</code> </dt> <dd>
<p>For syntax errors - the line number where the error occurred.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.end_lineno">
<code>end_lineno</code> </dt> <dd>
<p>For syntax errors - the end line number where the error occurred. Can be <code>None</code> if not present.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.text">
<code>text</code> </dt> <dd>
<p>For syntax errors - the text where the error occurred.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.offset">
<code>offset</code> </dt> <dd>
<p>For syntax errors - the offset into the text where the error occurred.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.end_offset">
<code>end_offset</code> </dt> <dd>
<p>For syntax errors - the end offset into the text where the error occurred. Can be <code>None</code> if not present.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.10.</span></p> </div> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.TracebackException.msg">
<code>msg</code> </dt> <dd>
<p>For syntax errors - the compiler error message.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="traceback.TracebackException.from_exception">
<code>classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)</code> </dt> <dd>
<p>Capture an exception for later rendering. <em>limit</em>, <em>lookup_lines</em> and <em>capture_locals</em> are as for the <a class="reference internal" href="#traceback.StackSummary" title="traceback.StackSummary"><code>StackSummary</code></a> class.</p> <p>Note that when locals are captured, they are also shown in the traceback.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="traceback.TracebackException.print">
<code>print(*, file=None, chain=True)</code> </dt> <dd>
<p>Print to <em>file</em> (default <code>sys.stderr</code>) the exception information returned by <a class="reference internal" href="functions#format" title="format"><code>format()</code></a>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="traceback.TracebackException.format">
<code>format(*, chain=True)</code> </dt> <dd>
<p>Format the exception.</p> <p>If <em>chain</em> is not <code>True</code>, <a class="reference internal" href="#traceback.TracebackException.__cause__" title="traceback.TracebackException.__cause__"><code>__cause__</code></a> and <a class="reference internal" href="#traceback.TracebackException.__context__" title="traceback.TracebackException.__context__"><code>__context__</code></a> will not be formatted.</p> <p>The return value is a generator of strings, each ending in a newline and some containing internal newlines. <a class="reference internal" href="#traceback.print_exception" title="traceback.print_exception"><code>print_exception()</code></a> is a wrapper around this method which just prints the lines to a file.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="traceback.TracebackException.format_exception_only">
<code>format_exception_only()</code> </dt> <dd>
<p>Format the exception part of the traceback.</p> <p>The return value is a generator of strings, each ending in a newline.</p> <p>The generator emits the exception’s message followed by its notes (if it has any). The exception message is normally a single string; however, for <a class="reference internal" href="exceptions#SyntaxError" title="SyntaxError"><code>SyntaxError</code></a> exceptions, it consists of several lines that (when printed) display detailed information about where the syntax error occurred.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>The exception’s <a class="reference internal" href="exceptions#BaseException.__notes__" title="BaseException.__notes__"><code>notes</code></a> are now included in the output.</p> </div> </dd>
</dl> </dd>
</dl> </section> <section id="stacksummary-objects"> <h2>
<code>StackSummary</code> Objects</h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> <p><code>StackSummary</code> objects represent a call stack ready for formatting.</p> <dl class="py class"> <dt class="sig sig-object py" id="traceback.StackSummary">
<code>class traceback.StackSummary</code> </dt> <dd>
<dl class="py method"> <dt class="sig sig-object py" id="traceback.StackSummary.extract">
<code>classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)</code> </dt> <dd>
<p>Construct a <code>StackSummary</code> object from a frame generator (such as is returned by <a class="reference internal" href="#traceback.walk_stack" title="traceback.walk_stack"><code>walk_stack()</code></a> or <a class="reference internal" href="#traceback.walk_tb" title="traceback.walk_tb"><code>walk_tb()</code></a>).</p> <p>If <em>limit</em> is supplied, only this many frames are taken from <em>frame_gen</em>. If <em>lookup_lines</em> is <code>False</code>, the returned <a class="reference internal" href="#traceback.FrameSummary" title="traceback.FrameSummary"><code>FrameSummary</code></a> objects will not have read their lines in yet, making the cost of creating the <code>StackSummary</code> cheaper (which may be valuable if it may not actually get formatted). If <em>capture_locals</em> is <code>True</code> the local variables in each <code>FrameSummary</code> are captured as object representations.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Exceptions raised from <a class="reference internal" href="functions#repr" title="repr"><code>repr()</code></a> on a local variable (when <em>capture_locals</em> is <code>True</code>) are no longer propagated to the caller.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="traceback.StackSummary.from_list">
<code>classmethod from_list(a_list)</code> </dt> <dd>
<p>Construct a <code>StackSummary</code> object from a supplied list of <a class="reference internal" href="#traceback.FrameSummary" title="traceback.FrameSummary"><code>FrameSummary</code></a> objects or old-style list of tuples. Each tuple should be a 4-tuple with <em>filename</em>, <em>lineno</em>, <em>name</em>, <em>line</em> as the elements.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="traceback.StackSummary.format">
<code>format()</code> </dt> <dd>
<p>Returns a list of strings ready for printing. Each string in the resulting list corresponds to a single <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">frame</span></a> from the stack. Each string ends in a newline; the strings may contain internal newlines as well, for those items with source text lines.</p> <p>For long sequences of the same frame and line, the first few repetitions are shown, followed by a summary line stating the exact number of further repetitions.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Long sequences of repeated frames are now abbreviated.</p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="traceback.StackSummary.format_frame_summary">
<code>format_frame_summary(frame_summary)</code> </dt> <dd>
<p>Returns a string for printing one of the <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">frames</span></a> involved in the stack. This method is called for each <a class="reference internal" href="#traceback.FrameSummary" title="traceback.FrameSummary"><code>FrameSummary</code></a> object to be printed by <a class="reference internal" href="#traceback.StackSummary.format" title="traceback.StackSummary.format"><code>StackSummary.format()</code></a>. If it returns <code>None</code>, the frame is omitted from the output.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd>
</dl> </dd>
</dl> </section> <section id="framesummary-objects"> <h2>
<code>FrameSummary</code> Objects</h2> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> <p>A <code>FrameSummary</code> object represents a single <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">frame</span></a> in a <a class="reference internal" href="../reference/datamodel#traceback-objects"><span class="std std-ref">traceback</span></a>.</p> <dl class="py class"> <dt class="sig sig-object py" id="traceback.FrameSummary">
<code>class traceback.FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)</code> </dt> <dd>
<p>Represents a single <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">frame</span></a> in the <a class="reference internal" href="../reference/datamodel#traceback-objects"><span class="std std-ref">traceback</span></a> or stack that is being formatted or printed. It may optionally have a stringified version of the frame’s locals included in it. If <em>lookup_line</em> is <code>False</code>, the source code is not looked up until the <code>FrameSummary</code> has the <a class="reference internal" href="#traceback.FrameSummary.line" title="traceback.FrameSummary.line"><code>line</code></a> attribute accessed (which also happens when casting it to a <a class="reference internal" href="stdtypes#tuple" title="tuple"><code>tuple</code></a>). <a class="reference internal" href="#traceback.FrameSummary.line" title="traceback.FrameSummary.line"><code>line</code></a> may be directly provided, and will prevent line lookups happening at all. <em>locals</em> is an optional local variable dictionary, and if supplied the variable representations are stored in the summary for later display.</p> <p><code>FrameSummary</code> instances have the following attributes:</p> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.FrameSummary.filename">
<code>filename</code> </dt> <dd>
<p>The filename of the source code for this frame. Equivalent to accessing <a class="reference internal" href="../reference/datamodel#codeobject.co_filename" title="codeobject.co_filename"><code>f.f_code.co_filename</code></a> on a <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">frame object</span></a> <em>f</em>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.FrameSummary.lineno">
<code>lineno</code> </dt> <dd>
<p>The line number of the source code for this frame.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.FrameSummary.name">
<code>name</code> </dt> <dd>
<p>Equivalent to accessing <a class="reference internal" href="../reference/datamodel#codeobject.co_name" title="codeobject.co_name"><code>f.f_code.co_name</code></a> on a <a class="reference internal" href="../reference/datamodel#frame-objects"><span class="std std-ref">frame object</span></a> <em>f</em>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="traceback.FrameSummary.line">
<code>line</code> </dt> <dd>
<p>A string representing the source code for this frame, with leading and trailing whitespace stripped. If the source is not available, it is <code>None</code>.</p> </dd>
</dl> </dd>
</dl> </section> <section id="traceback-examples"> <span id="traceback-example"></span><h2>Traceback Examples</h2> <p>This simple example implements a basic read-eval-print loop, similar to (but less useful than) the standard Python interactive interpreter loop. For a more complete implementation of the interpreter loop, refer to the <a class="reference internal" href="code#module-code" title="code: Facilities to implement read-eval-print loops."><code>code</code></a> module.</p> <pre data-language="python">import sys, traceback

def run_user_code(envdir):
    source = input("&gt;&gt;&gt; ")
    try:
        exec(source, envdir)
    except Exception:
        print("Exception in user code:")
        print("-"*60)
        traceback.print_exc(file=sys.stdout)
        print("-"*60)

envdir = {}
while True:
    run_user_code(envdir)
</pre> <p>The following example demonstrates the different ways to print and format the exception and traceback:</p> <pre data-language="python">import sys, traceback

def lumberjack():
    bright_side_of_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError:
    exc = sys.exception()
    print("*** print_tb:")
    traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
    print("*** print_exception:")
    traceback.print_exception(exc, limit=2, file=sys.stdout)
    print("*** print_exc:")
    traceback.print_exc(limit=2, file=sys.stdout)
    print("*** format_exc, first and last line:")
    formatted_lines = traceback.format_exc().splitlines()
    print(formatted_lines[0])
    print(formatted_lines[-1])
    print("*** format_exception:")
    print(repr(traceback.format_exception(exc)))
    print("*** extract_tb:")
    print(repr(traceback.extract_tb(exc.__traceback__)))
    print("*** format_tb:")
    print(repr(traceback.format_tb(exc.__traceback__)))
    print("*** tb_lineno:", exc.__traceback__.tb_lineno)
</pre> <p>The output for the example would look similar to this:</p> <pre data-language="none">*** print_tb:
  File "&lt;doctest...&gt;", line 10, in &lt;module&gt;
    lumberjack()
*** print_exception:
Traceback (most recent call last):
  File "&lt;doctest...&gt;", line 10, in &lt;module&gt;
    lumberjack()
  File "&lt;doctest...&gt;", line 4, in lumberjack
    bright_side_of_life()
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
  File "&lt;doctest...&gt;", line 10, in &lt;module&gt;
    lumberjack()
  File "&lt;doctest...&gt;", line 4, in lumberjack
    bright_side_of_life()
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
 '  File "&lt;doctest default[0]&gt;", line 10, in &lt;module&gt;\n    lumberjack()\n',
 '  File "&lt;doctest default[0]&gt;", line 4, in lumberjack\n    bright_side_of_life()\n',
 '  File "&lt;doctest default[0]&gt;", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n',
 'IndexError: tuple index out of range\n']
*** extract_tb:
[&lt;FrameSummary file &lt;doctest...&gt;, line 10 in &lt;module&gt;&gt;,
 &lt;FrameSummary file &lt;doctest...&gt;, line 4 in lumberjack&gt;,
 &lt;FrameSummary file &lt;doctest...&gt;, line 7 in bright_side_of_life&gt;]
*** format_tb:
['  File "&lt;doctest default[0]&gt;", line 10, in &lt;module&gt;\n    lumberjack()\n',
 '  File "&lt;doctest default[0]&gt;", line 4, in lumberjack\n    bright_side_of_life()\n',
 '  File "&lt;doctest default[0]&gt;", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n']
*** tb_lineno: 10
</pre> <p>The following example shows the different ways to print and format the stack:</p> <pre data-language="python">&gt;&gt;&gt; import traceback
&gt;&gt;&gt; def another_function():
...     lumberstack()
...
&gt;&gt;&gt; def lumberstack():
...     traceback.print_stack()
...     print(repr(traceback.extract_stack()))
...     print(repr(traceback.format_stack()))
...
&gt;&gt;&gt; another_function()
  File "&lt;doctest&gt;", line 10, in &lt;module&gt;
    another_function()
  File "&lt;doctest&gt;", line 3, in another_function
    lumberstack()
  File "&lt;doctest&gt;", line 6, in lumberstack
    traceback.print_stack()
[('&lt;doctest&gt;', 10, '&lt;module&gt;', 'another_function()'),
 ('&lt;doctest&gt;', 3, 'another_function', 'lumberstack()'),
 ('&lt;doctest&gt;', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
['  File "&lt;doctest&gt;", line 10, in &lt;module&gt;\n    another_function()\n',
 '  File "&lt;doctest&gt;", line 3, in another_function\n    lumberstack()\n',
 '  File "&lt;doctest&gt;", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']
</pre> <p>This last example demonstrates the final few formatting functions:</p> <pre data-language="pycon3">&gt;&gt;&gt; import traceback
&gt;&gt;&gt; traceback.format_list([('spam.py', 3, '&lt;module&gt;', 'spam.eggs()'),
...                        ('eggs.py', 42, 'eggs', 'return "bacon"')])
['  File "spam.py", line 3, in &lt;module&gt;\n    spam.eggs()\n',
 '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
&gt;&gt;&gt; an_error = IndexError('tuple index out of range')
&gt;&gt;&gt; traceback.format_exception_only(type(an_error), an_error)
['IndexError: tuple index out of range\n']
</pre> </section> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/library/traceback.html" class="_attribution-link">https://docs.python.org/3.12/library/traceback.html</a>
  </p>
</div>