From 23296de73eaa0a977a1e327f4096cc229fadc1bc Mon Sep 17 00:00:00 2001 From: Zac Hatfield-Dodds Date: Tue, 1 Mar 2022 20:54:41 -0800 Subject: [PATCH 1/6] PEP 678: clarify internals and heading --- pep-0678.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/pep-0678.rst b/pep-0678.rst index df3b97c880f..fd955737f8d 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -140,10 +140,10 @@ are collecting multiple exception objects to handle together. [1]_ Specification ============= -``BaseException`` gains a new read-only attribute ``__notes__``, an initially -empty tuple, and a new method ``.add_note(note: str)``. ``note`` is added to -the exception's notes, which appear in the standard traceback after the -exception string. A ``TypeError`` is raised if ``note`` is not a string. +``BaseException`` gains a new new method ``.add_note(note: str)``. Notes are +exposed as a tuple via the read-only attribute ``__notes__``, which is backed +by an internal list, and appear in the standard traceback after the exception +string. ``.add_note()`` raises ``TypeError`` if ``note`` is not a string. ``del err.__notes__`` clears the contents of the ``__notes__`` attribute, leaving it an empty tuple as if ``.add_note()`` had never been called. This @@ -319,8 +319,8 @@ proposed ``__notes__`` semantics, but this would be rarely and inconsistently applicable. -Store notes in ``ExceptionGroup``\ s ------------------------------------- +Store notes in ``ExceptionGroup``\ s, but not other ``Exception``\ s +-------------------------------------------------------------------- Initial discussions proposed making a more focussed change by thinking about how to associate messages with the nested exceptions in ``ExceptionGroup`` s, such as a list of notes or mapping of exceptions to notes. However, this would From ab5f09373a74f0a6926677d863099a5d54c62c8b Mon Sep 17 00:00:00 2001 From: Zac Hatfield-Dodds Date: Tue, 1 Mar 2022 22:21:42 -0800 Subject: [PATCH 2/6] PEP 678: omit impl details --- pep-0678.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pep-0678.rst b/pep-0678.rst index fd955737f8d..6f10942a69f 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -141,9 +141,9 @@ Specification ============= ``BaseException`` gains a new new method ``.add_note(note: str)``. Notes are -exposed as a tuple via the read-only attribute ``__notes__``, which is backed -by an internal list, and appear in the standard traceback after the exception -string. ``.add_note()`` raises ``TypeError`` if ``note`` is not a string. +exposed as a tuple via the read-only attribute ``__notes__``, and appear in +the standard traceback after the exception string. ``.add_note()`` raises +``TypeError`` if ``note`` is not a string. ``del err.__notes__`` clears the contents of the ``__notes__`` attribute, leaving it an empty tuple as if ``.add_note()`` had never been called. This From 7c28ab44f2a5af783cc1bbff8c86b04b54aa3e1b Mon Sep 17 00:00:00 2001 From: Zac Hatfield-Dodds Date: Tue, 1 Mar 2022 22:59:07 -0800 Subject: [PATCH 3/6] PEP 678: clarify rejected idea --- pep-0678.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/pep-0678.rst b/pep-0678.rst index 6f10942a69f..1c274ee79b5 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -319,15 +319,16 @@ proposed ``__notes__`` semantics, but this would be rarely and inconsistently applicable. -Store notes in ``ExceptionGroup``\ s, but not other ``Exception``\ s --------------------------------------------------------------------- -Initial discussions proposed making a more focussed change by thinking about -how to associate messages with the nested exceptions in ``ExceptionGroup`` s, -such as a list of notes or mapping of exceptions to notes. However, this would -force a remarkably awkward API and retains a lesser form of the -cross-referencing problem discussed under "use ``print()``" above; if this PEP -is rejected we prefer the status quo. Finally, of course, ``__notes__`` are -not only useful with ``ExceptionGroup``\ s! +Don't attach notes to ``Exception``\ s, just store them in ``ExceptionGroup``\ s +-------------------------------------------------------------------------------- +The initial motivation for this PEP was to associate a note with each error +in an ``ExceptionGroup``. At the cost of a remarkably awkward API and the +cross-referencing problem discussed under "use ``print()``" above, this +use-case could be supported by storing notes on the ``ExceptionGroup`` +instance instead of on each exception it contains. + +We believe that the cleaner interface, and other use-cases described above, +are sufficient to justify the more general feature proposed by this PEP. From 24912782305b6447f77ef1fed50b2b2b6bc618c8 Mon Sep 17 00:00:00 2001 From: Zac Hatfield-Dodds Date: Wed, 2 Mar 2022 00:02:23 -0800 Subject: [PATCH 4/6] PEP 678: link cross-reference --- pep-0678.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/pep-0678.rst b/pep-0678.rst index 1c274ee79b5..ad9f3cbfe41 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -59,6 +59,7 @@ therefore propose to add: Example usage ------------- +:: >>> try: ... raise TypeError('bad type') @@ -198,6 +199,8 @@ implements ``.add_note()`` and ``__notes__``. Rejected Ideas ============== +.. _print_idea: + Use ``print()`` (or ``logging``, etc.) -------------------------------------- Reporting explanatory or contextual information about an error by printing or @@ -323,7 +326,7 @@ Don't attach notes to ``Exception``\ s, just store them in ``ExceptionGroup``\ s -------------------------------------------------------------------------------- The initial motivation for this PEP was to associate a note with each error in an ``ExceptionGroup``. At the cost of a remarkably awkward API and the -cross-referencing problem discussed under "use ``print()``" above, this +cross-referencing problem discussed `above `__, this use-case could be supported by storing notes on the ``ExceptionGroup`` instance instead of on each exception it contains. From 0a2098663aba87a2465678a905b11ea168c71e64 Mon Sep 17 00:00:00 2001 From: Zac Hatfield-Dodds Date: Wed, 2 Mar 2022 23:08:48 -0800 Subject: [PATCH 5/6] PEP 678: final details update --- pep-0678.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pep-0678.rst b/pep-0678.rst index ad9f3cbfe41..631e4c81fea 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -143,8 +143,9 @@ Specification ``BaseException`` gains a new new method ``.add_note(note: str)``. Notes are exposed as a tuple via the read-only attribute ``__notes__``, and appear in -the standard traceback after the exception string. ``.add_note()`` raises -``TypeError`` if ``note`` is not a string. +the standard traceback after the exception string. ``.add_note()`` replaces +``__notes__`` with a new tuple equal to ``__notes__ + (note,)``, if ``note`` +is a string, raising ``TypeError`` otherwise. ``del err.__notes__`` clears the contents of the ``__notes__`` attribute, leaving it an empty tuple as if ``.add_note()`` had never been called. This From 0d150fae5a52cb95da33f76996ac714b925110ee Mon Sep 17 00:00:00 2001 From: Zac Hatfield-Dodds Date: Thu, 3 Mar 2022 00:15:45 -0800 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> --- pep-0678.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pep-0678.rst b/pep-0678.rst index 631e4c81fea..22a04dc76cf 100644 --- a/pep-0678.rst +++ b/pep-0678.rst @@ -143,9 +143,9 @@ Specification ``BaseException`` gains a new new method ``.add_note(note: str)``. Notes are exposed as a tuple via the read-only attribute ``__notes__``, and appear in -the standard traceback after the exception string. ``.add_note()`` replaces +the standard traceback after the exception string. ``.add_note(note)`` replaces ``__notes__`` with a new tuple equal to ``__notes__ + (note,)``, if ``note`` -is a string, raising ``TypeError`` otherwise. +is a string, and raises ``TypeError`` otherwise. ``del err.__notes__`` clears the contents of the ``__notes__`` attribute, leaving it an empty tuple as if ``.add_note()`` had never been called. This