https://github.com/python/cpython/commit/f394ee5eaf6d6d8f45e0478e77d4dbff25c... commit: f394ee5eaf6d6d8f45e0478e77d4dbff25c6bea7 branch: master author: torsava <torsava@redhat.com> committer: Berker Peksag <berker.peksag@gmail.com> date: 2018-08-02T19:08:59+03:00 summary: 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> files: M Doc/library/traceback.rst M Lib/traceback.py diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 55d331c996a1..7ac3cacd3d1c 100644 --- a/Doc/library/traceback.rst +++ b/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 - 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 @@ The module defines the following functions: .. 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 @@ 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 - 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 ee8c73914032..afab0a4b91f1 100644 --- a/Lib/traceback.py +++ b/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 - 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 @@ 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. - - 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