bpo-26389: Allow passing an exception object in the traceback module (GH-22610)

The format_exception(), format_exception_only(), and
print_exception() functions can now take an exception object as a positional-only argument.

Co-Authored-By: Matthias Bussonnier <bussonniermatthias@gmail.com>

1 files changed, 32 insertions, 11 deletions

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index 462a6a5..c233f18 100644
--- a/Doc/library/traceback.rst
+++ b/Doc/library/traceback.rst
@@ -36,7 +36,8 @@ The module defines the following functions:
        Added negative *limit* support.
 
 
-.. function:: print_exception(etype, value, tb, limit=None, file=None, chain=True)
+.. function:: print_exception(exc, /[, value, tb], limit=None, \
+                              file=None, chain=True)
 
    Print exception information and stack trace entries from traceback object
    *tb* to *file*. This differs from :func:`print_tb` in the following
@@ -45,7 +46,7 @@ The module defines the following functions:
    * if *tb* is not ``None``, it prints a header ``Traceback (most recent
      call last):``
 
-   * it prints the exception *etype* and *value* after the stack trace
+   * it prints the exception type and *value* after the stack trace
 
    .. index:: single: ^ (caret); marker
 
@@ -53,6 +54,10 @@ The module defines the following functions:
      format, it prints the line where the syntax error occurred with a caret
      indicating the approximate position of the error.
 
+   Since Python 3.10, instead of passing *value* and *tb*, an exception object
+   can be passed as the first argument. If *value* and *tb* are provided, the
+   first argument is ignored in order to provide backwards compatibility.
+
    The optional *limit* argument has the same meaning as for :func:`print_tb`.
    If *chain* is true (the default), then chained exceptions (the
    :attr:`__cause__` or :attr:`__context__` attributes of the exception) will be
@@ -62,6 +67,10 @@ The module defines the following functions:
    .. 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.
+
 
 .. function:: print_exc(limit=None, file=None, chain=True)
 
@@ -121,18 +130,26 @@ The module defines the following functions:
    text line is not ``None``.
 
 
-.. function:: format_exception_only(etype, value)
+.. function:: format_exception_only(exc, /[, value])
+
+   Format the exception part of a traceback using an exception value such as
+   given by ``sys.last_value``.  The return value is a list of strings, each
+   ending in a newline.  Normally, the list contains a single string; however,
+   for :exc:`SyntaxError` exceptions, it contains several lines that (when
+   printed) display detailed information about where the syntax error occurred.
+   The message indicating which exception occurred is the always last string in
+   the list.
 
-   Format the exception part of a traceback.  The arguments are the exception
-   type and value such as given by ``sys.last_type`` and ``sys.last_value``.
-   The return value is a list of strings, each ending in a newline.  Normally,
-   the list contains a single string; however, for :exc:`SyntaxError`
-   exceptions, it contains several lines that (when printed) display detailed
-   information about where the syntax error occurred.  The message indicating
-   which exception occurred is the always last string in the list.
+   Since Python 3.10, instead of passing *value*, an exception object
+   can be passed as the first argument.  If *value* is provided, the first
+   argument is ignored in order to provide backwards compatibility.
 
+   .. versionchanged:: 3.10
+      The *etype* parameter has been renamed to *exc* and is now
+      positional-only.
 
-.. function:: format_exception(etype, value, tb, limit=None, chain=True)
+
+.. function:: format_exception(exc, /[, value, tb], limit=None, chain=True)
 
    Format a stack trace and the exception information.  The arguments  have the
    same meaning as the corresponding arguments to :func:`print_exception`.  The
@@ -143,6 +160,10 @@ The module defines the following functions:
    .. 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`.
+
 
 .. function:: format_exc(limit=None, chain=True)