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:

..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::

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

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

..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)

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 afull stack trace.

..index::

single: tb_frame (traceback attribute)

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

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`,

* 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 nowwritable.

(Contributed by Nathaniel J. Smith in:issue:`30579`.)

* When using the:option:`-m` switch, ``sys.path[0]`` is now eagerly expanded