Skip to content

gh-135751: traceback: add recent_first and show_lines parameter #135752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

gh-135751: traceback: add recent_first and show_lines parameter #135752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
634f3be
add show_lines
methane Jun 16, 2025
a0b4b70
add test
methane Jun 16, 2025
979423f
add recent_first parameter to traceback functions
methane Jun 19, 2025
6038d11
add test for recent_first
methane Jun 20, 2025
ded22f3
add doc
methane Jun 17, 2025
b7454fb
add whatsnew entry
methane Jun 17, 2025
2efd9fb
add whats'new entry and news entry
methane Jun 20, 2025
fc0bf9b
fix doc
methane Jun 20, 2025
878ea1d
Apply suggestions from code review
methane Jun 20, 2025
78dcf35
remove unrelated change
methane Jun 20, 2025
abaa598
Apply suggestions from code review
methane Jun 20, 2025
6bb5450
Apply suggestions from code review
methane Jun 20, 2025
8d38237
fix doc
methane Jun 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 133 additions & 26 deletions Doc/library/traceback.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ The module's API can be divided into two parts:
Module-Level Functions
----------------------

.. function:: print_tb(tb, limit=None, file=None)
.. function:: print_tb(tb, limit=None, file=None, *, show_lines=True, recent_first=False)

Print up to *limit* stack trace entries from
:ref:`traceback object <traceback-objects>` *tb* (starting
Expand All @@ -63,6 +63,16 @@ Module-Level Functions
:term:`file <file object>` or :term:`file-like object` to
receive the output.

If *show_lines* is true (the default), source code lines will be included in the output.

If *recent_first* is true, the most recent stack trace entries are printed
first, otherwise the oldest entries are printed first. The default is false.
``recent_first=True`` is useful for showing stack traces in places where
people see the top of the stack trace first, such as in a web browser.
``recent_first=False`` is useful for showing stack traces in places where
people see the bottom of the stack trace first, such as a console or log
files watched with :command:`tail -f`.

.. note::

The meaning of the *limit* parameter is different than the meaning
Expand All @@ -74,9 +84,12 @@ Module-Level Functions
.. versionchanged:: 3.5
Added negative *limit* support.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.


.. function:: print_exception(exc, /[, value, tb], limit=None, \
file=None, chain=True)
file=None, chain=True, *, show_lines=True, recent_first=False)

Print exception information and stack trace entries from
:ref:`traceback object <traceback-objects>`
Expand Down Expand Up @@ -105,39 +118,58 @@ Module-Level Functions
printed as well, like the interpreter itself does when printing an unhandled
exception.

If *show_lines* is true, source code lines are included in the output.

If *recent_first* is true, the most recent stack trace entries are printed
first, otherwise the oldest entries are printed first. The default is false.

.. versionchanged:: 3.5
The *etype* argument is ignored and inferred from the type of *value*.

.. versionchanged:: 3.10
The *etype* parameter has been renamed to *exc* and is now
positional-only.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.


.. function:: print_exc(limit=None, file=None, chain=True)
.. function:: print_exc(limit=None, file=None, chain=True, *, show_lines=True, recent_first=False)

This is a shorthand for ``print_exception(sys.exception(), limit=limit, file=file,
chain=chain)``.
chain=chain, show_lines=show_lines, recent_first=recent_first)``.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.

.. function:: print_last(limit=None, file=None, chain=True)

.. function:: print_last(limit=None, file=None, chain=True, *, show_lines=True, recent_first=False)

This is a shorthand for ``print_exception(sys.last_exc, limit=limit, file=file,
chain=chain)``. In general it will work only after an exception has reached
an interactive prompt (see :data:`sys.last_exc`).
chain=chain, show_lines=show_lines, recent_first=recent_first)``.
In general it will work only after an exception has reached an interactive
prompt (see :data:`sys.last_exc`).

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.


.. function:: print_stack(f=None, limit=None, file=None)
.. function:: print_stack(f=None, limit=None, file=None, *, show_lines=True, recent_first=False)

Print up to *limit* stack trace entries (starting from the invocation
point) if *limit* is positive. Otherwise, print the last ``abs(limit)``
entries. If *limit* is omitted or ``None``, all entries are printed.
The optional *f* argument can be used to specify an alternate
:ref:`stack frame <frame-objects>`
to start. The optional *file* argument has the same meaning as for
:func:`print_tb`.
:func:`print_tb`. If *show_lines* is true, source code lines are
included in the output.

.. versionchanged:: 3.5
Added negative *limit* support.
Added negative *limit* support.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.


.. function:: extract_tb(tb, limit=None)
Expand All @@ -161,21 +193,29 @@ Module-Level Functions
arguments have the same meaning as for :func:`print_stack`.


.. function:: print_list(extracted_list, file=None)
.. function:: print_list(extracted_list, file=None, *, show_lines=True)

Print the list of tuples as returned by :func:`extract_tb` or
:func:`extract_stack` as a formatted stack trace to the given file.
If *file* is ``None``, the output is written to :data:`sys.stderr`.
If *show_lines* is true, source code lines are included in the output.

.. versionchanged:: next
Added the *show_lines* parameter.


.. function:: format_list(extracted_list)
.. function:: format_list(extracted_list, *, show_lines=True)

Given a list of tuples or :class:`FrameSummary` objects as returned by
:func:`extract_tb` or :func:`extract_stack`, return a list of strings ready
for printing. Each string in the resulting list corresponds to the item with
the same index in the argument list. Each string ends in a newline; the
strings may contain internal newlines as well, for those items whose source
text line is not ``None``.
text line is not ``None``. If *show_lines* is ``True``, source code lines
are included in the output.

.. versionchanged:: next
Added the *show_lines* parameter.


.. function:: format_exception_only(exc, /[, value], *, show_group=False)
Expand Down Expand Up @@ -208,36 +248,60 @@ Module-Level Functions
*show_group* parameter was added.


.. function:: format_exception(exc, /[, value, tb], limit=None, chain=True)
.. function:: format_exception(exc, /[, value, tb], limit=None, chain=True, *, show_lines=True, recent_first=False, show_group=False)

Format a stack trace and the exception information. The arguments have the
same meaning as the corresponding arguments to :func:`print_exception`. The
return value is a list of strings, each ending in a newline and some
containing internal newlines. When these lines are concatenated and printed,
exactly the same text is printed as does :func:`print_exception`.

If *show_lines* is true, source code lines are included in the output.
If *recent_first* is true, the most recent stack trace entries are printed
first, otherwise the oldest entries are printed first. The default is false.

.. versionchanged:: 3.5
The *etype* argument is ignored and inferred from the type of *value*.

.. versionchanged:: 3.10
This function's behavior and signature were modified to match
:func:`print_exception`.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.

.. function:: format_exc(limit=None, chain=True)

.. function:: format_exc(limit=None, chain=True, *, show_lines=True, recent_first=False)

This is like ``print_exc(limit)`` but returns a string instead of printing to
a file.

If *show_lines* is true, source code lines are included in the output.
If *recent_first* is true, the most recent stack trace entries are printed
first, otherwise the oldest entries are printed first. The default is false.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.


.. function:: format_tb(tb, limit=None, *, show_lines=True, recent_first=False)

.. function:: format_tb(tb, limit=None)
A shorthand for ``format_list(extract_tb(tb, limit), show_lines=show_lines)``.

A shorthand for ``format_list(extract_tb(tb, limit))``.
If *recent_first* is true, ``reversed(extract_tb(tb, limit))`` is used.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.

.. function:: format_stack(f=None, limit=None)

A shorthand for ``format_list(extract_stack(f, limit))``.
.. function:: format_stack(f=None, limit=None, *, show_lines=True, recent_first=False)

A shorthand for ``format_list(extract_stack(f, limit), show_lines=show_lines)``.

If *recent_first* is true, ``reversed(extract_stack(f, limit))`` is used.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.

.. function:: clear_frames(tb)

Expand Down Expand Up @@ -283,7 +347,7 @@ storing this information by avoiding holding references to
In addition, they expose more options to configure the output compared to
the module-level functions described above.

.. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)
.. class:: TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=False, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

Capture an exception for later rendering. The meaning of *limit*,
*lookup_lines* and *capture_locals* are as for the :class:`StackSummary`
Expand All @@ -309,6 +373,10 @@ the module-level functions described above.
.. versionchanged:: 3.11
Added the *max_group_width* and *max_group_depth* parameters.

.. versionchanged:: next
Changed *lookup_lines* default to ``False`` to avoid overhead when
formatting exceptions with ``show_lines=False``.

.. attribute:: __cause__

A :class:`!TracebackException` of the original
Expand Down Expand Up @@ -391,21 +459,35 @@ the module-level functions described above.

For syntax errors - the compiler error message.

.. classmethod:: from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False)
.. classmethod:: from_exception(exc, *, limit=None, lookup_lines=False, capture_locals=False)

Capture an exception for later rendering. *limit*, *lookup_lines* and
*capture_locals* are as for the :class:`StackSummary` class.

Note that when locals are captured, they are also shown in the traceback.

.. method:: print(*, file=None, chain=True)
.. versionchanged:: next
Changed *lookup_lines* default to ``False`` to avoid overhead when
formatting exceptions with ``show_lines=False``.

.. method:: print(*, file=None, chain=True, show_lines=True, recent_first=False)

Print to *file* (default ``sys.stderr``) the exception information returned by
:meth:`format`.

If *show_lines* is true, source code lines are included in the output.

If *recent_first* is true, the exception is printed first followed by stack
trace by "most recent call first" order.
Otherwise, the stack trace is printed first by "most recent call last" order
followed by the exception.

.. versionadded:: 3.11

.. method:: format(*, chain=True)
.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.

.. method:: format(*, chain=True, show_lines=True, recent_first=False)

Format the exception.

Expand All @@ -416,6 +498,16 @@ the module-level functions described above.
some containing internal newlines. :func:`~traceback.print_exception`
is a wrapper around this method which just prints the lines to a file.

If *show_lines* is true, source code lines are included in the output.

If *recent_first* is true, the exception is printed first followed by stack
trace by "most recent call first" order.
Otherwise, the stack trace is printed first by "most recent call last" order
followed by the exception.

.. versionchanged:: next
Added the *show_lines* and *recent_first* parameters.

.. method:: format_exception_only(*, show_group=False)

Format the exception part of the traceback.
Expand Down Expand Up @@ -449,7 +541,7 @@ the module-level functions described above.

.. class:: StackSummary

.. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)
.. classmethod:: extract(frame_gen, *, limit=None, lookup_lines=False, capture_locals=False)

Construct a :class:`!StackSummary` object from a frame generator (such as
is returned by :func:`~traceback.walk_stack` or
Expand All @@ -467,14 +559,18 @@ the module-level functions described above.
Exceptions raised from :func:`repr` on a local variable (when
*capture_locals* is ``True``) are no longer propagated to the caller.

.. versionchanged:: next
Changed *lookup_lines* default to ``False`` to avoid overhead when
formatting traceback with ``show_lines=False``.

.. classmethod:: from_list(a_list)

Construct a :class:`!StackSummary` object from a supplied list of
:class:`FrameSummary` objects or old-style list of tuples. Each tuple
should be a 4-tuple with *filename*, *lineno*, *name*, *line* as the
elements.

.. method:: format()
.. method:: format(*, show_lines=True)

Returns a list of strings ready for printing. Each string in the
resulting list corresponds to a single :ref:`frame <frame-objects>` from
Expand All @@ -486,19 +582,30 @@ the module-level functions described above.
repetitions are shown, followed by a summary line stating the exact
number of further repetitions.

If *show_lines* is true, includes source code lines in the output.

.. versionchanged:: 3.6
Long sequences of repeated frames are now abbreviated.

.. method:: format_frame_summary(frame_summary)
.. versionchanged:: next
Added the *show_lines* parameter.

.. method:: format_frame_summary(frame_summary, *, show_lines=True, **kwargs)

Returns a string for printing one of the :ref:`frames <frame-objects>`
involved in the stack.
This method is called for each :class:`FrameSummary` object to be
printed by :meth:`StackSummary.format`. If it returns ``None``, the
frame is omitted from the output.

The keyword argument *show_lines*, if ``True``, includes source code
lines in the output.

.. versionadded:: 3.11

.. versionchanged:: next
Added the *show_lines* parameter.


:class:`!FrameSummary` Objects
------------------------------
Expand Down
15 changes: 15 additions & 0 deletions Doc/whatsnew/3.15.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,21 @@ tarfile
and :cve:`2025-4435`.)


traceback
----------

* Add new *show_lines* and *recent_first* keyword only arguments to
the :mod:`traceback` functions.

The *show_lines* argument controls whether source code lines are displayed.
It is default to ``True``.

The *recent_first* argument controls whether the most recent frames are
displayed first or last in the traceback. It affects whether the exception
is displayed at the top or bottom of the traceback. It is default to ``False``.
(Contributed by Inada Naoki in :gh:`135751`)


zlib
----

Expand Down
Loading
Loading