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>

Doc/library/traceback.rst

@@ -88,14 +88,16 @@ The module defines the following functions:
 
 .. function:: extract_tb(tb, limit=None)
 
-   Return a list of "pre-processed" stack trace entries extracted from the
+   Return a :class:`StackSummary` object representing a list of "pre-processed"
-   traceback object *tb*.  It is useful for alternate formatting of
+   stack trace entries extracted from the traceback object *tb*.  It is useful
-   stack traces.  The optional *limit* argument has the same meaning as for
+   for alternate formatting of stack traces.  The optional *limit* argument has
-   :func:`print_tb`.  A "pre-processed" stack trace entry is a 4-tuple
+   the same meaning as for :func:`print_tb`.  A "pre-processed" stack trace
-   (*filename*, *line number*, *function name*, *text*) representing the
+   entry is a :class:`FrameSummary` object containing attributes
-   information that is usually printed for a stack trace.  The *text* is a
+   :attr:`~FrameSummary.filename`, :attr:`~FrameSummary.lineno`,
-   string with leading and trailing whitespace stripped; if the source is
+   :attr:`~FrameSummary.name`, and :attr:`~FrameSummary.line` representing the
-   not available it is ``None``.
+   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 @@ The module defines the following functions:
 
 .. function:: format_list(extracted_list)
 
-   Given a list of tuples as returned by :func:`extract_tb` or
+   Given a list of tuples or :class:`FrameSummary` objects as returned by
-   :func:`extract_stack`, return a list of strings ready for printing. Each
+   :func:`extract_tb` or :func:`extract_stack`, return a list of strings ready
-   string in the resulting list corresponds to the item with the same index in
+   for printing.  Each string in the resulting list corresponds to the item with
-   the argument list.  Each string ends in a newline; the strings may contain
+   the same index in the argument list.  Each string ends in a newline; the
-   internal newlines as well, for those items whose source text line is not
+   strings may contain internal newlines as well, for those items whose source
-   ``None``.
+   text line is not ``None``.
 
 
 .. function:: format_exception_only(etype, value)
@@ -293,9 +295,9 @@ capture data for later printing in a lightweight fashion.
 
    .. classmethod:: from_list(a_list)
 
-      Construct a :class:`StackSummary` object from a supplied old-style list
+      Construct a :class:`StackSummary` object from a supplied list of
-      of tuples. Each tuple should be a 4-tuple with filename, lineno, name,
+      :class:`FrameSummary` objects or old-style list of tuples.  Each tuple
-      line as the elements.
+      should be a 4-tuple with filename, lineno, name, line as the elements.
 
    .. method:: format()
 

Lib/traceback.py

@@ -25,10 +25,12 @@ def print_list(extracted_list, file=None):
         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 or FrameSummary objects as returned by
+    extract_tb() or extract_stack(), return a list of strings ready
+    for printing.
 
-    Given a list of tuples 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 @@ def format_tb(tb, limit=None):
     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
+    pre-processed stack trace entry is a FrameSummary object
-    number, function name, text) representing the information that is
+    containing attributes filename, lineno, name, and line
-    usually printed for a stack trace.  The text is a string with
+    representing the information that is usually printed for a stack
-    leading and trailing whitespace stripped; if the source is not
+    trace.  The line is a string with leading and trailing
-    available it is None.
+    whitespace stripped; if the source is not available it is None.
     """
     return StackSummary.extract(walk_tb(tb), limit=limit)
 
@@ -359,10 +363,9 @@ def extract(klass, frame_gen, *, limit=None, lookup_lines=True,
 
     @classmethod
     def from_list(klass, a_list):
-        """Create a StackSummary from a simple list of tuples.
+        """
-
+        Create a StackSummary object from a supplied list of
-        This method supports the older Python API. Each tuple should be a
+        FrameSummary objects or old-style list of tuples.
-        4-tuple with (filename, lineno, name, line) elements.
         """
         # While doing a fast-path check for isinstance(a_list, StackSummary) is
         # appealing, idlelib.run.cleanup_traceback and other similar code may