bpo-30579: Docs for dynamic traceback creation (GH-5653)
diff --git a/Doc/library/types.rst b/Doc/library/types.rst
index bbc1d13..67cd4d7 100644
--- a/Doc/library/types.rst
+++ b/Doc/library/types.rst
@@ -198,16 +198,23 @@
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
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 8420fb6..8b127a0 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -950,7 +950,7 @@
.. 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 @@
.. versionadded:: 3.4
+ .. _traceback-objects:
+
Traceback objects
.. index::
object: traceback
@@ -1015,31 +1017,51 @@
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
- trace (towards the frame where the exception occurred), or ``None`` if there is
- no next level; :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.
+ 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.
+
+ .. 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
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index 3b4ba6e..c3761c5 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -398,6 +398,12 @@
``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
===========