[3.12] gh-101100: Improve documentation of `TracebackType` attributes (GH-112884...

gh-101100: Improve documentation of `TracebackType` attributes (GH-112884)
(cherry picked from commit 96f64a2b1b4e3d4902848c63e42717a9c5539e03)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index bbefa43f39bc5f16de1ade8a3b6b69db94ece87b..ad441bb3b106d9d64fa580561f4f3124b15d865b 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -5458,8 +5458,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:

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 55ac361b1903a2a063d9645a50f534c640ef4bb6..d7baf04cee1d4a8710524367e83bd34a052afd39 100644 (file)
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -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::
@@ -205,7 +206,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

diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index 9b100383572affc1f31991996ea068e397f5adef..3ce7ede4dec3a58c775b601925c578f9c88404ec 100644 (file)
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -376,11 +376,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

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index f4bb381b7a2a65733552995e9a5a2629d8e1a358..5aaeab8ad63ec23cffaf1385ad901d2f0f72f299 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -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)
@@ -1352,26 +1353,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)
@@ -1380,27 +1385,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.
+
+.. 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 frame object if the exception occurred in a
+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
-finally clause.
-
-Accessing ``tb_frame`` raises an :ref:`auditing event <auditing>`
-``object.__getattr__`` with arguments ``obj`` and ``"tb_frame"``.
+: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
-there is no next level.
+.. attribute:: traceback.tb_next
 
-.. versionchanged:: 3.7
-   Traceback objects can now be explicitly instantiated from Python code,
-   and the ``tb_next`` attribute of existing instances can be updated.
+   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
+      This attribute is now writable
 
 
 Slice objects

diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index 108e5293bc4b1c92add731d01ca1aa57337f0b8f..1a977d2cce7b55864f319d645f6064ba3fe8b880 100644 (file)
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -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`,

diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index fbd495e3d8651af46c3949ac5ba4037514e99726..4f7b018bd4c4f75795883c261bc83071827eeb87 100644 (file)
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -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