bpo-30579: Docs for dynamic traceback creation (GH-5653)
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