mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-03 16:39:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

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

Browse source
This commit is contained in:
Nick Coghlan 2018-02-13 18:10:58 +10:00 • committed by GitHub
parent da6c3da6c3
commit aec7532ed3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 48 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

46
Doc/reference/datamodel.rst
View file

@ -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
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