From 0a8ff63db665fed2d3d0246ffaf77cf06c864c03 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Sat, 9 Sep 2023 22:10:15 +0100 Subject: [PATCH 1/5] gh-109184: traceback module doc is out of date w.r.t notes --- Doc/library/traceback.rst | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 3eb77fc3df5709..2f8b5ba6d72191 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -139,11 +139,11 @@ The module defines the following functions: 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. + ending in a newline. The list contains the exception's message, which is + normally a single string; however, for :exc:`SyntaxError` exceptions, it + contains several lines that (when printed) display detailed information + about where the syntax error occurred. Following the message, the list + contains the exception's notes. Since Python 3.10, instead of passing *value*, an exception object can be passed as the first argument. If *value* is provided, the first @@ -330,20 +330,17 @@ capture data for later printing in a lightweight fashion. some containing internal newlines. :func:`~traceback.print_exception` is a wrapper around this method which just prints the lines to a file. - The message indicating which exception occurred is always the last - string in the output. - .. method:: format_exception_only(*, show_group=False) Format the exception part of the traceback. The return value is a generator of strings, each ending in a newline. - When *show_group* is ``False``, the generator normally emits a single - string; however, for :exc:`SyntaxError` exceptions, it emits several - lines that (when printed) display detailed information about where - the syntax error occurred. The message indicating which exception - occurred is always the last string in the output. + When *show_group* is ``False``, the generator emits the exception's + message followed by its notes (if it has any). The exception message + is normally a single string; however, for :exc:`SyntaxError` exceptions, + it consists of several lines that (when printed) display detailed + information about where the syntax error occurred. When *show_group* is ``True``, and the exception is an instance of :exc:`BaseExceptionGroup`, the nested exceptions are included as From c7127e8f1f3aa2253a841397d1d0ad9ce2f96e7c Mon Sep 17 00:00:00 2001 From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Date: Tue, 12 Sep 2023 12:07:14 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Alex Waygood --- Doc/library/traceback.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 2f8b5ba6d72191..6cce8cc99b4bf1 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -143,7 +143,10 @@ The module defines the following functions: normally a single string; however, for :exc:`SyntaxError` exceptions, it contains several lines that (when printed) display detailed information about where the syntax error occurred. Following the message, the list - contains the exception's notes. + contains the exception's :attr:`notes `. + + .. versionchanged:: 3.11 + The returned list now includes any notes attached to the exception. Since Python 3.10, instead of passing *value*, an exception object can be passed as the first argument. If *value* is provided, the first From c87513706e948ce22e8545bd242fd03b38da9ae3 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Tue, 12 Sep 2023 12:09:37 +0100 Subject: [PATCH 3/5] add 3.11 change note --- Doc/library/traceback.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 6cce8cc99b4bf1..dc8197ade27605 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -357,6 +357,7 @@ capture data for later printing in a lightweight fashion. .. versionchanged:: 3.11 Added the *max_group_width* and *max_group_depth* parameters. + The exception's notes are now included in the output. From db3d8b3546135ba903e7cd2f7bc10cc5f780b289 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Tue, 12 Sep 2023 12:26:26 +0100 Subject: [PATCH 4/5] move versionchanged around --- Doc/library/traceback.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index dc8197ade27605..78d80de9da3b10 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -238,6 +238,12 @@ capture data for later printing in a lightweight fashion. group's exceptions array. The formatted output is truncated when either limit is exceeded. + .. versionchanged:: 3.10 + Added the *compact* parameter. + + .. versionchanged:: 3.11 + Added the *max_group_width* and *max_group_depth* parameters. + .. attribute:: __cause__ A :class:`TracebackException` of the original ``__cause__``. @@ -349,17 +355,12 @@ capture data for later printing in a lightweight fashion. :exc:`BaseExceptionGroup`, the nested exceptions are included as well, recursively, with indentation relative to their nesting depth. + .. versionchanged:: 3.11 + The exception's notes are now included in the output. + .. versionchanged:: 3.13 Added the *show_group* parameter. - .. versionchanged:: 3.10 - Added the *compact* parameter. - - .. versionchanged:: 3.11 - Added the *max_group_width* and *max_group_depth* parameters. - The exception's notes are now included in the output. - - :class:`StackSummary` Objects ----------------------------- From ec3599046b03e8f0e0e1b353c43312af77f10b48 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Tue, 12 Sep 2023 15:05:06 +0100 Subject: [PATCH 5/5] fix nit --- Doc/library/traceback.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 78d80de9da3b10..67ee73d4b2e1e5 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -145,9 +145,6 @@ The module defines the following functions: about where the syntax error occurred. Following the message, the list contains the exception's :attr:`notes `. - .. versionchanged:: 3.11 - The returned list now includes any notes attached to the exception. - 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. @@ -156,6 +153,9 @@ The module defines the following functions: The *etype* parameter has been renamed to *exc* and is now positional-only. + .. versionchanged:: 3.11 + The returned list now includes any notes attached to the exception. + .. function:: format_exception(exc, /[, value, tb], limit=None, chain=True)