bpo-30579: Docs for dynamic traceback creation (GH-5653)

(cherry picked from commit aec7532ed3)

Co-authored-by: Nick Coghlan <ncoghlan@gmail.com>

Doc/library/types.rst

@@ -198,16 +198,23 @@ Standard names are defined for the following types:
          Defaults to ``None``. Previously the attribute was optional.
 
 
-.. data:: TracebackType
+.. class:: TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)
 
    The type of traceback objects such as found in ``sys.exc_info()[2]``.
 
+   See :ref:`the language reference <traceback-objects>` for details of the
+   available attributes and operations, and guidance on creating tracebacks
+   dynamically.
+
 
 .. 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.
+
 
 .. data:: GetSetDescriptorType
 

Doc/reference/datamodel.rst

@@ -950,7 +950,7 @@ Internal types
       .. index:: object: frame
 
       Frame objects represent execution frames.  They may occur in traceback objects
-      (see below).
+      (see below), and are also passed to registered trace functions.
 
       .. index::
          single: f_back (frame attribute)
@@ -1003,6 +1003,8 @@ Internal types
 
          .. versionadded:: 3.4
 
+   .. _traceback-objects:
+
    Traceback objects
       .. index::
          object: traceback
@@ -1015,31 +1017,51 @@ Internal types
          single: sys.last_traceback
 
       Traceback objects represent a stack trace of an exception.  A traceback object
-      is created when an exception occurs.  When the search for an exception handler
+      is implicitly created when an exception occurs, and may also be explicitly
+      created by calling :class:`types.TracebackType`.
+
+      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()``. When the program contains no suitable
+      tuple returned by ``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``.
 
+      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.
+
       .. index::
-         single: tb_next (traceback attribute)
          single: tb_frame (traceback attribute)
          single: tb_lineno (traceback attribute)
          single: tb_lasti (traceback attribute)
          statement: try
 
-      Special read-only attributes: :attr:`tb_next` is the next level in the stack
+      Special read-only attributes:
-      trace (towards the frame where the exception occurred), or ``None`` if there is
+      :attr:`tb_frame` points to the execution frame of the current level;
-      no next level; :attr:`tb_frame` points to the execution frame of the current
+      :attr:`tb_lineno` gives the line number where the exception occurred;
-      level; :attr:`tb_lineno` gives the line number where the exception occurred;
+      :attr:`tb_lasti` indicates the precise instruction.
-      :attr:`tb_lasti` indicates the precise instruction.  The line number and last
+      The line number and last instruction in the traceback may differ from the
-      instruction in the traceback may differ from the line number of its frame object
+      line number of its frame object if the exception occurred in a
-      if the exception occurred in a :keyword:`try` statement with no matching except
+      :keyword:`try` statement with no matching except clause or with a
-      clause or with a finally clause.
+      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.
+
+    .. versionchanged:: 3.7
+       Traceback objects can now be explicitly instantiated from Python code,
+       and the ``tb_next`` attribute of existing instances can be updated.
 
    Slice objects
       .. index:: builtin: slice

Doc/whatsnew/3.7.rst

@@ -398,6 +398,12 @@ Other Language Changes
   ``format(str(self), '')``.
   (Contributed by Serhiy Storchaka in :issue:`28974`.)
 
+* 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.
+  (Contributed by Nathaniel J. Smith in :issue:`30579`.)
+
 
 New Modules
 ===========