From 37a734738cc66898139a9dfc161e0828131f5b12 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Thu, 6 Jan 2022 18:17:38 +0000 Subject: [PATCH 1/5] Revert "remove __note__ documentation" This reverts commit 939a1f65054a50fc5414a9af496d17d00eb7d7f0. --- Doc/library/traceback.rst | 8 +++++ Doc/tutorial/errors.rst | 62 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index df4a38c955511b..766eb46bdc8c6e 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -236,6 +236,14 @@ capture data for later printing in a lightweight fashion. The ``__suppress_context__`` value from the original exception. + .. attribute:: __note__ + + The ``__note__`` value from the original exception, which is + string or ``None``. If it is not ``None`` is it formatted in + the traceback after the exception string. + + .. versionadded:: 3.11 + .. attribute:: stack A :class:`StackSummary` representing the traceback. diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index ad1ef841bffc41..3db687362aa521 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -551,3 +551,65 @@ the following pattern:: ... raise ExceptionGroup("Test Failures", excs) ... + +Enriching Exceptions with Notes +=============================== + +When an exception is created in order to be raised, it is usually initialized +with information that describes the error that has occurred. There are cases +where it is useful to add information after the exception was caught. For this +purpose, exceptions have a mutable field ``__note__`` that can be string or +``None`` (``None`` by default). If it is a string, it is included in the +formatted tracebacks after the exception. :: + + >>> try: + ... raise TypeError('bad type') + ... except Exception as e: + ... e.__note__ = 'Add some information' + ... raise + ... + Traceback (most recent call last): + File "", line 2, in + TypeError: bad type + Add some information + >>> + +For example, when collecting exceptions into an exception group, we may want +to add context information for the individual errors. In the following each +exception in the group has a note indicating when this error has occurred. :: + + >>> def f(): + ... raise OSError('operation failed') + ... + >>> excs = [] + >>> for i in range(3): + ... try: + ... f() + ... except Exception as e: + ... e.__note__ = f'Happened in Iteration {i+1}' + ... excs.append(e) + ... + >>> raise ExceptionGroup('We have some problems', excs) + + Exception Group Traceback (most recent call last): + | File "", line 1, in + | ExceptionGroup: We have some problems + +-+---------------- 1 ---------------- + | Traceback (most recent call last): + | File "", line 3, in + | File "", line 2, in f + | OSError: operation failed + | Happened in Iteration 1 + +---------------- 2 ---------------- + | Traceback (most recent call last): + | File "", line 3, in + | File "", line 2, in f + | OSError: operation failed + | Happened in Iteration 2 + +---------------- 3 ---------------- + | Traceback (most recent call last): + | File "", line 3, in + | File "", line 2, in f + | OSError: operation failed + | Happened in Iteration 3 + +------------------------------------ + >>> From 75bfd314d2beb8de94eb654c96cfc07b0b7986fb Mon Sep 17 00:00:00 2001 From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Date: Mon, 17 Jan 2022 13:00:17 +0000 Subject: [PATCH 2/5] reword intro --- Doc/tutorial/errors.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 3db687362aa521..e93efba1436146 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -558,8 +558,8 @@ Enriching Exceptions with Notes When an exception is created in order to be raised, it is usually initialized with information that describes the error that has occurred. There are cases where it is useful to add information after the exception was caught. For this -purpose, exceptions have a mutable field ``__note__`` that can be string or -``None`` (``None`` by default). If it is a string, it is included in the +purpose, exceptions have a ``__note__`` attribute that can be assigned a string or +``None`` value (``None`` by default). If it is a string, it is included in the formatted tracebacks after the exception. :: >>> try: From 729c10c336c20c8d5df3434b591238aa9e6f4fd2 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Mon, 18 Apr 2022 18:49:52 +0100 Subject: [PATCH 3/5] Update for accepted version of the PEP --- Doc/library/traceback.rst | 8 ++++---- Doc/tutorial/errors.rst | 12 +++++++----- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 766eb46bdc8c6e..796309c6cf0bb9 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -236,11 +236,11 @@ capture data for later printing in a lightweight fashion. The ``__suppress_context__`` value from the original exception. - .. attribute:: __note__ + .. attribute:: __notes__ - The ``__note__`` value from the original exception, which is - string or ``None``. If it is not ``None`` is it formatted in - the traceback after the exception string. + The ``__notes__`` value from the original exception, or ``None`` + if the exception does not have any notes. If it is not ``None`` + is it formatted in the traceback after the exception string. .. versionadded:: 3.11 diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index e93efba1436146..ac8edc2fccbf13 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -558,20 +558,22 @@ Enriching Exceptions with Notes When an exception is created in order to be raised, it is usually initialized with information that describes the error that has occurred. There are cases where it is useful to add information after the exception was caught. For this -purpose, exceptions have a ``__note__`` attribute that can be assigned a string or -``None`` value (``None`` by default). If it is a string, it is included in the -formatted tracebacks after the exception. :: +purpose, exceptions have a method ``add_node(note)`` that accepts a string and +adds it to the exception's notes list. The standard traceback includes all +notes, in the order they were added, after the exception. :: >>> try: ... raise TypeError('bad type') ... except Exception as e: - ... e.__note__ = 'Add some information' + ... e.add_note('Add some information') + ... e.add_note('Add some more information') ... raise ... Traceback (most recent call last): File "", line 2, in TypeError: bad type Add some information + Add some more information >>> For example, when collecting exceptions into an exception group, we may want @@ -586,7 +588,7 @@ exception in the group has a note indicating when this error has occurred. :: ... try: ... f() ... except Exception as e: - ... e.__note__ = f'Happened in Iteration {i+1}' + ... e.add_note(f'Happened in Iteration {i+1}') ... excs.append(e) ... >>> raise ExceptionGroup('We have some problems', excs) From 192bf861b738bf56897adee6cf36d7d4e8b273b1 Mon Sep 17 00:00:00 2001 From: Irit Katriel Date: Mon, 18 Apr 2022 23:01:09 +0100 Subject: [PATCH 4/5] apply comments from gps --- Doc/tutorial/errors.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index ac8edc2fccbf13..825fd08f56ca0b 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -558,9 +558,9 @@ Enriching Exceptions with Notes When an exception is created in order to be raised, it is usually initialized with information that describes the error that has occurred. There are cases where it is useful to add information after the exception was caught. For this -purpose, exceptions have a method ``add_node(note)`` that accepts a string and -adds it to the exception's notes list. The standard traceback includes all -notes, in the order they were added, after the exception. :: +purpose, exceptions have a method ``add_note(note)`` that accepts a string and +adds it to the exception's notes list. The standard traceback rendering +includes all notes, in the order they were added, after the exception. :: >>> try: ... raise TypeError('bad type') From 8bf05ecc4accf5421b11091e72d371e618a1f19e Mon Sep 17 00:00:00 2001 From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> Date: Tue, 19 Apr 2022 16:12:15 +0100 Subject: [PATCH 5/5] Update example output (we added the sub-exception count after this PR was created) --- Doc/tutorial/errors.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 825fd08f56ca0b..6b766dd61f0551 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -594,7 +594,7 @@ exception in the group has a note indicating when this error has occurred. :: >>> raise ExceptionGroup('We have some problems', excs) + Exception Group Traceback (most recent call last): | File "", line 1, in - | ExceptionGroup: We have some problems + | ExceptionGroup: We have some problems (3 sub-exceptions) +-+---------------- 1 ---------------- | Traceback (most recent call last): | File "", line 3, in