mirror of
https://github.com/python/cpython.git
synced 2025-07-23 19:25:40 +00:00
Issue #17911: Tweak traceback documentation.
Changes: * Fixed reSt markup * Fixed cross references * Fixed a couple of typos
This commit is contained in:
Berker Peksag
parent
4a13cb94d3
commit
49f373bf66
1 changed files with 95 additions and 71 deletions
|
|
@ -138,16 +138,16 @@ The module defines the following functions:
|
|||
|
||||
.. function:: walk_stack(f)
|
||||
|
||||
Walk a stack following f.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 *Stack.extract*.
|
||||
Walk a stack following ``f.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`.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. function:: walk_tb(tb)
|
||||
|
||||
Walk a traceback following tb_next yielding the frame and line number for
|
||||
each frame. This helper is used with *Stack.extract*.
|
||||
Walk a traceback following ``tb_next`` yielding the frame and line number
|
||||
for each frame. This helper is used with :meth:`StackSummary.extract`.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
|
@ -156,118 +156,142 @@ The module also defines the following classes:
|
|||
:class:`TracebackException` Objects
|
||||
-----------------------------------
|
||||
|
||||
:class:`.TracebackException` objects are created from actual exceptions to
|
||||
.. versionadded:: 3.5
|
||||
|
||||
: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)
|
||||
|
||||
Capture an exception for later rendering. limit, lookup_lines and
|
||||
capture_locals=False are as for the :class:`.StackSummary` class.
|
||||
Capture an exception for later rendering. *limit*, *lookup_lines* and
|
||||
*capture_locals* are as for the :class:`StackSummary` class.
|
||||
|
||||
Note that when locals are captured, they are also shown in the traceback.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
.. attribute:: __cause__
|
||||
|
||||
.. classmethod:: `.from_exception`(exc, *, limit=None, lookup_lines=True, capture_locals=False)
|
||||
A :class:`TracebackException` of the original ``__cause__``.
|
||||
|
||||
Capture an exception for later rendering. limit, lookup_lines and
|
||||
capture_locals=False are as for the :class:`.StackSummary` class.
|
||||
.. attribute:: __context__
|
||||
|
||||
A :class:`TracebackException` of the original ``__context__``.
|
||||
|
||||
.. attribute:: __suppress_context__
|
||||
|
||||
The ``__suppress_context__`` value from the original exception.
|
||||
|
||||
.. attribute:: stack
|
||||
|
||||
A :class:`StackSummary` representing the traceback.
|
||||
|
||||
.. attribute:: exc_type
|
||||
|
||||
The class of the original traceback.
|
||||
|
||||
.. attribute:: filename
|
||||
|
||||
For syntax errors - the file name where the error occurred.
|
||||
|
||||
.. attribute:: lineno
|
||||
|
||||
For syntax errors - the line number where the error occurred.
|
||||
|
||||
.. attribute:: text
|
||||
|
||||
For syntax errors - the text where the error occurred.
|
||||
|
||||
.. attribute:: offset
|
||||
|
||||
For syntax errors - the offset into the text where the error occurred.
|
||||
|
||||
.. attribute:: msg
|
||||
|
||||
For syntax errors - the compiler error message.
|
||||
|
||||
.. classmethod:: from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)
|
||||
|
||||
Capture an exception for later rendering. *limit*, *lookup_lines* and
|
||||
*capture_locals* are as for the :class:`StackSummary` class.
|
||||
|
||||
Note that when locals are captured, they are also shown in the traceback.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. attribute:: `.__cause__` A TracebackException of the original *__cause__*.
|
||||
|
||||
.. attribute:: `.__context__` A TracebackException of the original *__context__*.
|
||||
.. attribute:: `.__suppress_context__` The *__suppress_context__* value from the
|
||||
original exception.
|
||||
.. attribute:: `.stack` A `StackSummary` representing the traceback.
|
||||
.. attribute:: `.exc_type` The class of the original traceback.
|
||||
.. attribute:: `.filename` For syntax errors - the filename where the error
|
||||
occured.
|
||||
.. attribute:: `.lineno` For syntax errors - the linenumber where the error
|
||||
occured.
|
||||
.. attribute:: `.text` For syntax errors - the text where the error
|
||||
occured.
|
||||
.. attribute:: `.offset` For syntax errors - the offset into the text where the
|
||||
error occured.
|
||||
.. attribute:: `.msg` For syntax errors - the compiler error message.
|
||||
|
||||
.. method:: TracebackException.format(*, chain=True)
|
||||
.. method:: format(*, chain=True)
|
||||
|
||||
Format the exception.
|
||||
|
||||
If chain is not *True*, *__cause__* and *__context__* will not be formatted.
|
||||
If *chain* is not ``True``, ``__cause__`` and ``__context__`` will not
|
||||
be formatted.
|
||||
|
||||
The return value is a generator of strings, each ending in a newline and
|
||||
some containing internal newlines. `print_exception` is a wrapper around
|
||||
this method which just prints the lines to a file.
|
||||
some containing internal newlines. :func:`~traceback.print_exception`
|
||||
is a wrapper around this method which just prints the lines to a file.
|
||||
|
||||
The message indicating which exception occurred is always the last
|
||||
string in the output.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. method:: TracebackException.format_exception_only()
|
||||
.. method:: format_exception_only()
|
||||
|
||||
Format the exception part of the traceback.
|
||||
|
||||
The return value is a generator of strings, each ending in a newline.
|
||||
|
||||
Normally, the generator emits a single string; however, for
|
||||
SyntaxError exceptions, it emites several lines that (when
|
||||
:exc:`SyntaxError` exceptions, it emits several lines that (when
|
||||
printed) display detailed information about where the syntax
|
||||
error occurred.
|
||||
|
||||
The message indicating which exception occurred is always the last
|
||||
string in the output.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
|
||||
:class:`StackSummary` Objects
|
||||
-----------------------------
|
||||
|
||||
:class:`.StackSummary` objects represent a call stack ready for formatting.
|
||||
.. versionadded:: 3.5
|
||||
|
||||
.. classmethod:: StackSummary.extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)
|
||||
:class:`StackSummary` objects represent a call stack ready for formatting.
|
||||
|
||||
Construct a StackSummary object from a frame generator (such as is returned by
|
||||
`walk_stack` or `walk_tb`.
|
||||
.. class:: StackSummary
|
||||
|
||||
If limit is supplied, only this many frames are taken from frame_gen.
|
||||
If lookup_lines is False, the returned FrameSummary objects will not have read
|
||||
their lines in yet, making the cost of creating the StackSummary cheaper (which
|
||||
may be valuable if it may not actually get formatted).
|
||||
If capture_locals is True the local variables in each *FrameSummary* are
|
||||
captured as object representations.
|
||||
.. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)
|
||||
|
||||
.. versionadded:: 3.5
|
||||
Construct a :class:`StackSummary` object from a frame generator (such as
|
||||
is returned by :func:`~traceback.walk_stack` or
|
||||
:func:`~traceback.walk_tb`).
|
||||
|
||||
.. classmethod:: StackSummary.from_list(a_list)
|
||||
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
|
||||
may not actually get formatted). If *capture_locals* is ``True`` the
|
||||
local variables in each :class:`FrameSummary` are captured as object
|
||||
representations.
|
||||
|
||||
Construct a StackSummary object from a supplied old-style list of tuples. Each
|
||||
tuple should be a 4-tuple with filename, lineno, name, line as the elements.
|
||||
.. classmethod:: from_list(a_list)
|
||||
|
||||
Construct a :class:`StackSummary` object from a supplied old-style list
|
||||
of tuples. Each tuple should be a 4-tuple with filename, lineno, name,
|
||||
line as the elements.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
||||
:class:`FrameSummary` Objects
|
||||
-----------------------------
|
||||
|
||||
FrameSummary objects represent a single frame in a traceback.
|
||||
.. versionadded:: 3.5
|
||||
|
||||
:class:`FrameSummary` objects represent a single frame in a traceback.
|
||||
|
||||
.. class:: FrameSummary(filename, lineno, name, lookup_line=True, locals=None, line=None)
|
||||
:noindex:
|
||||
|
||||
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
|
||||
locals included in it. If *lookup_line* is False, the source code is not
|
||||
looked up until the FrameSummary has the :attr:`line` attribute accessed (which
|
||||
also happens when casting it to a tuple). *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.
|
||||
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).
|
||||
: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.
|
||||
|
||||
.. _traceback-example:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue