add doc

Author: methane

Doc/library/traceback.rst

@@ -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
@@ -63,6 +63,19 @@ Module-Level Functions
    :term:`file <file object>` or :term:`file-like object` to
    receive the output.
 
+   If *show_lines* is false, source code lines are not 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.
+
+   .. note::
+      ``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
@@ -74,9 +87,12 @@ Module-Level Functions
    .. versionchanged:: 3.5
        Added negative *limit* support.
 
+   .. versionchanged:: next
+      Added *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>`
@@ -103,7 +119,13 @@ Module-Level Functions
    :attr:`~BaseException.__cause__` or :attr:`~BaseException.__context__`
    attributes of the exception) will be
    printed as well, like the interpreter itself does when printing an unhandled
-   exception.
+   exception.  If *show_lines* is ``False``, source code lines are not included
+   in the output.
+
+   If *show_lines* is false, source code lines are not 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*.
@@ -112,32 +134,46 @@ Module-Level Functions
       The *etype* parameter has been renamed to *exc* and is now
       positional-only.
 
+   .. versionchanged:: next
+      Added *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 *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 *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 ``False``, source code lines are
+   not included in the output.
 
    .. versionchanged:: 3.5
-          Added negative *limit* support.
+      Added negative *limit* support.
+
+   .. versionchanged:: next
+      Added *show_lines* and *recent_first* parameters.
 
 
 .. function:: extract_tb(tb, limit=None)
@@ -161,21 +197,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 ``False``, source code lines are not included in the output.
 
+   .. versionchanged:: next
+      Added *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 ``False``, source code lines
+   are not included in the output.
+
+   .. versionchanged:: next
+      Added *show_lines* parameter.
 
 
 .. function:: format_exception_only(exc, /[, value], *, show_group=False)
@@ -208,36 +252,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 false, source code lines are not 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 *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 false, source code lines are not 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.
 
-.. function:: format_tb(tb, limit=None)
+   .. versionchanged:: next
+      Added *show_lines* and *recent_first* parameters.
 
-   A shorthand for ``format_list(extract_tb(tb, limit))``.
 
+.. function:: format_tb(tb, limit=None, *, show_lines=True, recent_first=False)
 
-.. function:: format_stack(f=None, limit=None)
+   A shorthand for ``format_list(extract_tb(tb, limit), show_lines=show_lines)``.
 
-   A shorthand for ``format_list(extract_stack(f, limit))``.
+   If *recent_first* is true, ``reversed(extract_tb(tb, limit))`` is used.
+
+   .. versionchanged:: next
+      Added *show_lines* and *recent_first* parameters.
+
+
+.. 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 *show_lines* and *recent_first* parameters.
 
 .. function:: clear_frames(tb)
 
@@ -398,14 +466,24 @@ the module-level functions described above.
 
       Note that when locals are captured, they are also shown in the traceback.
 
-   .. method::  print(*, file=None, chain=True)
+   .. 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 false, source code lines from being 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 *show_lines* and *recent_first* parameters.
+
+   .. method:: format(*, chain=True, show_lines=True, recent_first=False, **kwargs)
 
       Format the exception.
 
@@ -416,6 +494,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 false, source code lines from being 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 *show_lines* and *recent_first* parameters.
+
    .. method::  format_exception_only(*, show_group=False)
 
       Format the exception part of the traceback.
@@ -474,7 +562,7 @@ the module-level functions described above.
       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
@@ -486,19 +574,31 @@ the module-level functions described above.
       repetitions are shown, followed by a summary line stating the exact
       number of further repetitions.
 
+      The keyword argument *show_lines*, if ``False``, prevents source code
+      lines from being included 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 ``False``, prevents source code
+      lines from being included in the output.
+
       .. versionadded:: 3.11
 
+      .. versionchanged:: next
+         Added the *show_lines* parameter.
+
 
 :class:`!FrameSummary` Objects
 ------------------------------