The module uses :ref:`traceback objects <traceback-objects>` --- these are
objects of type :class:`types.TracebackType`,
-which are assigned to the ``__traceback__`` field of :class:`BaseException` instances.
+which are assigned to the :attr:`~BaseException.__traceback__` field of
+:class:`BaseException` instances.
.. seealso::
.. function:: print_tb(tb, limit=None, file=None)
- Print up to *limit* stack trace entries from traceback object *tb* (starting
+ Print up to *limit* stack trace entries from
+ :ref:`traceback object <traceback-objects>` *tb* (starting
from the caller's frame) if *limit* is positive. Otherwise, print the last
``abs(limit)`` entries. If *limit* is omitted or ``None``, all entries are
printed. If *file* is omitted or ``None``, the output goes to
- ``sys.stderr``; otherwise it should be an open file or file-like object to
+ :data:`sys.stderr`; otherwise it should be an open
+ :term:`file <file object>` or :term:`file-like object` to
receive the output.
.. versionchanged:: 3.5
.. function:: print_exception(exc, /[, value, tb], limit=None, \
file=None, chain=True)
- Print exception information and stack trace entries from traceback object
+ Print exception information and stack trace entries from
+ :ref:`traceback object <traceback-objects>`
*tb* to *file*. This differs from :func:`print_tb` in the following
ways:
Print up to *limit* stack trace entries (starting from the invocation
point) if *limit* is positive. Otherwise, print the last ``abs(limit)``
entries. If *limit* is omitted or ``None``, all entries are printed.
- The optional *f* argument can be used to specify an alternate stack frame
+ The optional *f* argument can be used to specify an alternate
+ :ref:`stack frame <frame-objects>`
to start. The optional *file* argument has the same meaning as for
:func:`print_tb`.
.. function:: extract_tb(tb, limit=None)
Return a :class:`StackSummary` object representing a list of "pre-processed"
- stack trace entries extracted from the traceback object *tb*. It is useful
+ stack trace entries extracted from the
+ :ref:`traceback object <traceback-objects>` *tb*. It is useful
for alternate formatting of stack traces. The optional *limit* argument has
the same meaning as for :func:`print_tb`. A "pre-processed" stack trace
entry is a :class:`FrameSummary` object containing attributes
:attr:`~FrameSummary.filename`, :attr:`~FrameSummary.lineno`,
:attr:`~FrameSummary.name`, and :attr:`~FrameSummary.line` representing the
- information that is usually printed for a stack trace. The
- :attr:`~FrameSummary.line` is a string with leading and trailing
- whitespace stripped; if the source is not available it is ``None``.
+ information that is usually printed for a stack trace.
.. function:: extract_stack(f=None, limit=None)
- Extract the raw traceback from the current stack frame. The return value has
+ Extract the raw traceback from the current
+ :ref:`stack frame <frame-objects>`. The return value has
the same format as for :func:`extract_tb`. The optional *f* and *limit*
arguments have the same meaning as for :func:`print_stack`.
.. function:: format_exception_only(exc, /[, value], *, show_group=False)
Format the exception part of a traceback using an exception value such as
- given by ``sys.last_value``. The return value is a list of strings, each
+ given by :data:`sys.last_value`. 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 :exc:`SyntaxError` exceptions, it
contains several lines that (when printed) display detailed information
positional-only.
.. versionchanged:: 3.11
- The returned list now includes any notes attached to the exception.
+ The returned list now includes any
+ :attr:`notes <BaseException.__notes__>` attached to the exception.
.. versionchanged:: 3.13
*show_group* parameter was added.
.. function:: clear_frames(tb)
- Clears the local variables of all the stack frames in a traceback *tb*
- by calling the :meth:`clear` method of each frame object.
+ Clears the local variables of all the stack frames in a
+ :ref:`traceback <traceback-objects>` *tb*
+ by calling the :meth:`~frame.clear` method of each
+ :ref:`frame object <frame-objects>`.
.. versionadded:: 3.4
.. function:: walk_stack(f)
- Walk a stack following ``f.f_back`` from the given frame, yielding the frame
+ Walk a stack following :attr:`f.f_back <frame.f_back>` from the given frame,
+ yielding the frame
and line number for each frame. If *f* is ``None``, the current stack is
used. This helper is used with :meth:`StackSummary.extract`.
The module also defines the following classes:
-:class:`TracebackException` Objects
------------------------------------
+:class:`!TracebackException` Objects
+------------------------------------
.. versionadded:: 3.5
-:class:`TracebackException` objects are created from actual exceptions to
+:class:`!TracebackException` objects are created from actual exceptions to
capture data for later printing in a lightweight fashion.
.. class:: 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)
well, recursively, with indentation relative to their nesting depth.
.. versionchanged:: 3.11
- The exception's notes are now included in the output.
+ The exception's :attr:`notes <BaseException.__notes__>` are now
+ included in the output.
.. versionchanged:: 3.13
Added the *show_group* parameter.
-:class:`StackSummary` Objects
------------------------------
+:class:`!StackSummary` Objects
+------------------------------
.. versionadded:: 3.5
-:class:`StackSummary` objects represent a call stack ready for formatting.
+:class:`!StackSummary` objects represent a call stack ready for formatting.
.. class:: StackSummary
.. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)
- Construct a :class:`StackSummary` object from a frame generator (such as
+ Construct a :class:`!StackSummary` object from a frame generator (such as
is returned by :func:`~traceback.walk_stack` or
:func:`~traceback.walk_tb`).
If *limit* is supplied, only this many frames are taken from *frame_gen*.
If *lookup_lines* is ``False``, the returned :class:`FrameSummary`
objects will not have read their lines in yet, making the cost of
- creating the :class:`StackSummary` cheaper (which may be valuable if it
+ creating the :class:`!StackSummary` cheaper (which may be valuable if it
may not actually get formatted). If *capture_locals* is ``True`` the
- local variables in each :class:`FrameSummary` are captured as object
+ local variables in each :class:`!FrameSummary` are captured as object
representations.
.. versionchanged:: 3.12
.. classmethod:: from_list(a_list)
- Construct a :class:`StackSummary` object from a supplied list of
+ Construct a :class:`!StackSummary` object from a supplied list of
:class:`FrameSummary` objects or old-style list of tuples. Each tuple
- should be a 4-tuple with filename, lineno, name, line as the elements.
+ should be a 4-tuple with *filename*, *lineno*, *name*, *line* as the
+ elements.
.. method:: format()
Returns a list of strings ready for printing. Each string in the
- resulting list corresponds to a single frame from the stack.
+ resulting list corresponds to a single :ref:`frame <frame-objects>` from
+ the stack.
Each string ends in a newline; the strings may contain internal
newlines as well, for those items with source text lines.
.. method:: format_frame_summary(frame_summary)
- Returns a string for printing one of the frames involved in the stack.
+ Returns a string for printing one of the :ref:`frames <frame-objects>`
+ involved in the stack.
This method is called for each :class:`FrameSummary` object to be
printed by :meth:`StackSummary.format`. If it returns ``None``, the
frame is omitted from the output.
.. versionadded:: 3.11
-:class:`FrameSummary` Objects
------------------------------
+:class:`!FrameSummary` Objects
+------------------------------
.. versionadded:: 3.5
-A :class:`FrameSummary` object represents a single frame in a traceback.
+A :class:`!FrameSummary` object represents a single :ref:`frame <frame-objects>`
+in a :ref:`traceback <traceback-objects>`.
.. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)
- Represent a single frame in the traceback or stack that is being formatted
- or printed. It may optionally have a stringified version of the frames
+ Represents a single :ref:`frame <frame-objects>` in the
+ :ref:`traceback <traceback-objects>` or stack that is being formatted
+ or printed. It may optionally have a stringified version of the frame's
locals included in it. If *lookup_line* is ``False``, the source code is not
- looked up until the :class:`FrameSummary` has the :attr:`~FrameSummary.line`
- attribute accessed (which also happens when casting it to a tuple).
+ looked up until the :class:`!FrameSummary` has the :attr:`~FrameSummary.line`
+ attribute accessed (which also happens when casting it to a :class:`tuple`).
:attr:`~FrameSummary.line` may be directly provided, and will prevent line
lookups happening at all. *locals* is an optional local variable
dictionary, and if supplied the variable representations are stored in the
summary for later display.
+ :class:`!FrameSummary` instances have the following attributes:
+
+ .. attribute:: FrameSummary.filename
+
+ The filename of the source code for this frame. Equivalent to accessing
+ :attr:`f.f_code.co_filename <codeobject.co_filename>` on a
+ :ref:`frame object <frame-objects>` *f*.
+
+ .. attribute:: FrameSummary.lineno
+
+ The line number of the source code for this frame.
+
+ .. attribute:: FrameSummary.name
+
+ Equivalent to accessing :attr:`f.f_code.co_name <codeobject.co_name>` on
+ a :ref:`frame object <frame-objects>` *f*.
+
+ .. attribute:: FrameSummary.line
+
+ A string representing the source code for this frame, with leading and
+ trailing whitespace stripped.
+ If the source is not available, it is ``None``.
+
.. _traceback-example:
Traceback Examples
projects / thirdparty / Python / cpython.git / commitdiff
