diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Ftraceback.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Ftraceback.html | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Ftraceback.html b/devdocs/python~3.12/library%2Ftraceback.html new file mode 100644 index 00000000..f23623ac --- /dev/null +++ b/devdocs/python~3.12/library%2Ftraceback.html @@ -0,0 +1,265 @@ + <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(">>> ") + 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 "<doctest...>", line 10, in <module> + lumberjack() +*** print_exception: +Traceback (most recent call last): + File "<doctest...>", line 10, in <module> + lumberjack() + File "<doctest...>", line 4, in lumberjack + bright_side_of_life() +IndexError: tuple index out of range +*** print_exc: +Traceback (most recent call last): + File "<doctest...>", line 10, in <module> + lumberjack() + File "<doctest...>", 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 "<doctest default[0]>", line 10, in <module>\n lumberjack()\n', + ' File "<doctest default[0]>", line 4, in lumberjack\n bright_side_of_life()\n', + ' File "<doctest default[0]>", line 7, in bright_side_of_life\n return tuple()[0]\n ~~~~~~~^^^\n', + 'IndexError: tuple index out of range\n'] +*** extract_tb: +[<FrameSummary file <doctest...>, line 10 in <module>>, + <FrameSummary file <doctest...>, line 4 in lumberjack>, + <FrameSummary file <doctest...>, line 7 in bright_side_of_life>] +*** format_tb: +[' File "<doctest default[0]>", line 10, in <module>\n lumberjack()\n', + ' File "<doctest default[0]>", line 4, in lumberjack\n bright_side_of_life()\n', + ' File "<doctest default[0]>", 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">>>> import traceback +>>> def another_function(): +... lumberstack() +... +>>> def lumberstack(): +... traceback.print_stack() +... print(repr(traceback.extract_stack())) +... print(repr(traceback.format_stack())) +... +>>> another_function() + File "<doctest>", line 10, in <module> + another_function() + File "<doctest>", line 3, in another_function + lumberstack() + File "<doctest>", line 6, in lumberstack + traceback.print_stack() +[('<doctest>', 10, '<module>', 'another_function()'), + ('<doctest>', 3, 'another_function', 'lumberstack()'), + ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')] +[' File "<doctest>", line 10, in <module>\n another_function()\n', + ' File "<doctest>", line 3, in another_function\n lumberstack()\n', + ' File "<doctest>", 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">>>> import traceback +>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'), +... ('eggs.py', 42, 'eggs', 'return "bacon"')]) +[' File "spam.py", line 3, in <module>\n spam.eggs()\n', + ' File "eggs.py", line 42, in eggs\n return "bacon"\n'] +>>> an_error = IndexError('tuple index out of range') +>>> 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"> + © 2001–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> |