bpo-27910: Update documentation of traceback module (GH-6116)
In the documentation for the traceback module, the definitions of functions
extract_tb(), format_list() and classmethod StackSummary.from_list()
mention the old style 4-tuples that these functions used to return or accept.
Since Python 3.5, however, they return or accept a FrameSummary object
instead of a 4-tuple, or a StackSummary object instead of a list of 4-tuples.
Co-Authored-By: Berker Peksag <berker.peksag@gmail.com>
diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 55d331c..7ac3cacd 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -88,14 +88,16 @@
.. function:: extract_tb(tb, limit=None)
- Return a list of "pre-processed" stack trace entries extracted from the
- traceback object *tb*. It is useful for alternate formatting of
- stack traces. The optional *limit* argument has the same meaning as for
- :func:`print_tb`. A "pre-processed" stack trace entry is a 4-tuple
- (*filename*, *line number*, *function name*, *text*) representing the
- information that is usually printed for a stack trace. The *text* is a
- string with leading and trailing whitespace stripped; if the source is
- not available it is ``None``.
+ Return a :class:`StackSummary` object representing a list of "pre-processed"
+ stack trace entries extracted from the traceback object *tb*. It is useful
+ for alternate formatting of stack traces. The optional *limit* argument has
+ the same meaning as for :func:`print_tb`. A "pre-processed" stack trace
+ entry is a :class:`FrameSummary` object containing attributes
+ :attr:`~FrameSummary.filename`, :attr:`~FrameSummary.lineno`,
+ :attr:`~FrameSummary.name`, and :attr:`~FrameSummary.line` representing the
+ information that is usually printed for a stack trace. The
+ :attr:`~FrameSummary.line` is a string with leading and trailing
+ whitespace stripped; if the source is not available it is ``None``.
.. function:: extract_stack(f=None, limit=None)
@@ -107,12 +109,12 @@
.. function:: format_list(extracted_list)
- Given a list of tuples 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``.
+ 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``.
.. function:: format_exception_only(etype, value)
@@ -293,9 +295,9 @@
.. classmethod:: from_list(a_list)
- Construct a :class:`StackSummary` object from a supplied old-style list
- of tuples. Each tuple should be a 4-tuple with filename, lineno, name,
- line as the elements.
+ 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()
diff --git a/Lib/traceback.py b/Lib/traceback.py
index ee8c739..afab0a4 100644
--- a/Lib/traceback.py
+++ b/Lib/traceback.py
@@ -25,10 +25,12 @@
print(item, file=file, end="")
def format_list(extracted_list):
- """Format a list of traceback entry tuples for printing.
+ """Format a list of tuples or FrameSummary objects for printing.
- Given a list of tuples as returned by extract_tb() or
- extract_stack(), return a list of strings ready for printing.
+ Given a list of tuples or FrameSummary objects as returned by
+ extract_tb() or 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
@@ -55,15 +57,17 @@
return extract_tb(tb, limit=limit).format()
def extract_tb(tb, limit=None):
- """Return list of up to limit pre-processed entries from traceback.
+ """
+ Return a StackSummary object representing a list of
+ pre-processed entries from traceback.
This is useful for alternate formatting of stack traces. If
'limit' is omitted or None, all entries are extracted. A
- pre-processed stack trace entry is a quadruple (filename, line
- number, function name, text) representing the information that is
- usually printed for a stack trace. The text is a string with
- leading and trailing whitespace stripped; if the source is not
- available it is None.
+ pre-processed stack trace entry is a FrameSummary object
+ containing attributes filename, lineno, name, and line
+ representing the information that is usually printed for a stack
+ trace. The line is a string with leading and trailing
+ whitespace stripped; if the source is not available it is None.
"""
return StackSummary.extract(walk_tb(tb), limit=limit)
@@ -359,10 +363,9 @@
@classmethod
def from_list(klass, a_list):
- """Create a StackSummary from a simple list of tuples.
-
- This method supports the older Python API. Each tuple should be a
- 4-tuple with (filename, lineno, name, line) elements.
+ """
+ Create a StackSummary object from a supplied list of
+ FrameSummary objects or old-style list of tuples.
"""
# While doing a fast-path check for isinstance(a_list, StackSummary) is
# appealing, idlelib.run.cleanup_traceback and other similar code may