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>
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 @@
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 @@
* 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 @@
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 @@
.. 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 @@
text line is not ``None``.
-.. function:: format_exception_only(etype, value)
+.. function:: format_exception_only(exc, /[, value])
- 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.
+ 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.
+
+ 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 @@
.. 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)