mirror of
https://github.com/python/cpython
synced 2024-10-14 12:48:09 +00:00
gh-101100: Improve documentation of TracebackType
attributes (#112884)
This commit is contained in:
parent
54410e6bd9
commit
96f64a2b1b
|
@ -5461,8 +5461,9 @@ It is written as ``NotImplemented``.
|
|||
Internal Objects
|
||||
----------------
|
||||
|
||||
See :ref:`types` for this information. It describes stack frame objects,
|
||||
traceback objects, and slice objects.
|
||||
See :ref:`types` for this information. It describes
|
||||
:ref:`stack frame objects <frame-objects>`,
|
||||
:ref:`traceback objects <traceback-objects>`, and slice objects.
|
||||
|
||||
|
||||
.. _specialattrs:
|
||||
|
|
|
@ -16,7 +16,8 @@ interpreter.
|
|||
|
||||
.. index:: pair: object; traceback
|
||||
|
||||
The module uses traceback objects --- these are objects of type :class:`types.TracebackType`,
|
||||
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.
|
||||
|
||||
.. seealso::
|
||||
|
@ -212,7 +213,8 @@ The module defines the following functions:
|
|||
|
||||
.. function:: walk_tb(tb)
|
||||
|
||||
Walk a traceback following ``tb_next`` yielding the frame and line number
|
||||
Walk a traceback following :attr:`~traceback.tb_next` yielding the frame and
|
||||
line number
|
||||
for each frame. This helper is used with :meth:`StackSummary.extract`.
|
||||
|
||||
.. versionadded:: 3.5
|
||||
|
|
|
@ -378,11 +378,8 @@ Standard names are defined for the following types:
|
|||
|
||||
.. data:: FrameType
|
||||
|
||||
The type of frame objects such as found in ``tb.tb_frame`` if ``tb`` is a
|
||||
traceback object.
|
||||
|
||||
See :ref:`the language reference <frame-objects>` for details of the
|
||||
available attributes and operations.
|
||||
The type of :ref:`frame objects <frame-objects>` such as found in
|
||||
:attr:`tb.tb_frame <traceback.tb_frame>` if ``tb`` is a traceback object.
|
||||
|
||||
|
||||
.. data:: GetSetDescriptorType
|
||||
|
|
|
@ -1244,8 +1244,9 @@ Frame objects
|
|||
|
||||
.. index:: pair: object; frame
|
||||
|
||||
Frame objects represent execution frames. They may occur in traceback objects
|
||||
(see below), and are also passed to registered trace functions.
|
||||
Frame objects represent execution frames. They may occur in
|
||||
:ref:`traceback objects <traceback-objects>`,
|
||||
and are also passed to registered trace functions.
|
||||
|
||||
.. index::
|
||||
single: f_back (frame attribute)
|
||||
|
@ -1357,26 +1358,30 @@ Traceback objects
|
|||
single: sys.exception
|
||||
single: sys.last_traceback
|
||||
|
||||
Traceback objects represent a stack trace of an exception. A traceback object
|
||||
Traceback objects represent the stack trace of an :ref:`exception <tut-errors>`.
|
||||
A traceback object
|
||||
is implicitly created when an exception occurs, and may also be explicitly
|
||||
created by calling :class:`types.TracebackType`.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
Traceback objects can now be explicitly instantiated from Python code.
|
||||
|
||||
For implicitly created tracebacks, when the search for an exception handler
|
||||
unwinds the execution stack, at each unwound level a traceback object is
|
||||
inserted in front of the current traceback. When an exception handler is
|
||||
entered, the stack trace is made available to the program. (See section
|
||||
:ref:`try`.) It is accessible as the third item of the
|
||||
tuple returned by ``sys.exc_info()``, and as the ``__traceback__`` attribute
|
||||
tuple returned by :func:`sys.exc_info`, and as the ``__traceback__`` attribute
|
||||
of the caught exception.
|
||||
|
||||
When the program contains no suitable
|
||||
handler, the stack trace is written (nicely formatted) to the standard error
|
||||
stream; if the interpreter is interactive, it is also made available to the user
|
||||
as ``sys.last_traceback``.
|
||||
as :data:`sys.last_traceback`.
|
||||
|
||||
For explicitly created tracebacks, it is up to the creator of the traceback
|
||||
to determine how the ``tb_next`` attributes should be linked to form a
|
||||
full stack trace.
|
||||
to determine how the :attr:`~traceback.tb_next` attributes should be linked to
|
||||
form a full stack trace.
|
||||
|
||||
.. index::
|
||||
single: tb_frame (traceback attribute)
|
||||
|
@ -1385,27 +1390,40 @@ full stack trace.
|
|||
pair: statement; try
|
||||
|
||||
Special read-only attributes:
|
||||
:attr:`tb_frame` points to the execution frame of the current level;
|
||||
:attr:`tb_lineno` gives the line number where the exception occurred;
|
||||
:attr:`tb_lasti` indicates the precise instruction.
|
||||
The line number and last instruction in the traceback may differ from the
|
||||
line number of its frame object if the exception occurred in a
|
||||
:keyword:`try` statement with no matching except clause or with a
|
||||
finally clause.
|
||||
|
||||
Accessing ``tb_frame`` raises an :ref:`auditing event <auditing>`
|
||||
``object.__getattr__`` with arguments ``obj`` and ``"tb_frame"``.
|
||||
.. list-table::
|
||||
|
||||
* - .. attribute:: traceback.tb_frame
|
||||
- Points to the execution :ref:`frame <frame-objects>` of the current
|
||||
level.
|
||||
|
||||
Accessing this attribute raises an
|
||||
:ref:`auditing event <auditing>` ``object.__getattr__`` with arguments
|
||||
``obj`` and ``"tb_frame"``.
|
||||
|
||||
* - .. attribute:: traceback.tb_lineno
|
||||
- Gives the line number where the exception occurred
|
||||
|
||||
* - .. attribute:: traceback.tb_lasti
|
||||
- Indicates the "precise instruction".
|
||||
|
||||
The line number and last instruction in the traceback may differ from the
|
||||
line number of its :ref:`frame object <frame-objects>` if the exception
|
||||
occurred in a
|
||||
:keyword:`try` statement with no matching except clause or with a
|
||||
:keyword:`finally` clause.
|
||||
|
||||
.. index::
|
||||
single: tb_next (traceback attribute)
|
||||
|
||||
Special writable attribute: :attr:`tb_next` is the next level in the stack
|
||||
trace (towards the frame where the exception occurred), or ``None`` if
|
||||
.. attribute:: traceback.tb_next
|
||||
|
||||
The special writable attribute :attr:`!tb_next` is the next level in the
|
||||
stack trace (towards the frame where the exception occurred), or ``None`` if
|
||||
there is no next level.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
Traceback objects can now be explicitly instantiated from Python code,
|
||||
and the ``tb_next`` attribute of existing instances can be updated.
|
||||
This attribute is now writable
|
||||
|
||||
|
||||
Slice objects
|
||||
|
|
|
@ -1947,7 +1947,8 @@ traceback
|
|||
---------
|
||||
|
||||
New :func:`~traceback.walk_stack` and :func:`~traceback.walk_tb`
|
||||
functions to conveniently traverse frame and traceback objects.
|
||||
functions to conveniently traverse frame and
|
||||
:ref:`traceback objects <traceback-objects>`.
|
||||
(Contributed by Robert Collins in :issue:`17911`.)
|
||||
|
||||
New lightweight classes: :class:`~traceback.TracebackException`,
|
||||
|
|
|
@ -525,8 +525,8 @@ Other Language Changes
|
|||
|
||||
* In order to better support dynamic creation of stack traces,
|
||||
:class:`types.TracebackType` can now be instantiated from Python code, and
|
||||
the ``tb_next`` attribute on :ref:`tracebacks <traceback-objects>` is now
|
||||
writable.
|
||||
the :attr:`~traceback.tb_next` attribute on
|
||||
:ref:`tracebacks <traceback-objects>` is now writable.
|
||||
(Contributed by Nathaniel J. Smith in :issue:`30579`.)
|
||||
|
||||
* When using the :option:`-m` switch, ``sys.path[0]`` is now eagerly expanded
|
||||
|
|
Loading…
Reference in a new issue