PEP 678: Clarify how the notes tuple is updated and when it is copied (…

…#2377)

Co-authored-by: Irit Katriel <[email protected]>

pep-0678.rst

@@ -59,6 +59,7 @@ therefore propose to add:
 
 Example usage
 -------------
+::
 
    >>> try:
    ...     raise TypeError('bad type')
@@ -140,10 +141,11 @@ 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__``, and appear in
+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, 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
@@ -198,6 +200,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
@@ -319,15 +323,16 @@ proposed ``__notes__`` semantics, but this would be rarely and inconsistently
 applicable.
 
 
-Store notes in ``ExceptionGroup``\ 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 `above <print_idea>`__, 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.