PEP-678: exception notes are set by add_note(). __notes__ holds a tuple of the assigned notes

Author: iritkatriel

Doc/library/exceptions.rst

@@ -126,13 +126,22 @@ The following exceptions are used mostly as base classes for other exceptions.
              tb = sys.exc_info()[2]
              raise OtherException(...).with_traceback(tb)
 
-   .. attribute:: __note__
+   .. method:: add_note(note, / replace=False)
 
-      A mutable field which is :const:`None` by default and can be set to a string.
-      If it is not :const:`None`, it is included in the traceback. This field can
-      be used to enrich exceptions after they have been caught.
+      If ``note`` is a string, it is added to the exception's notes which appear
+      in the standard traceback after the exception string. If ``replace`` is
+      true, all previously existing notes are removed before the new one is added.
+      To clear all notes, use ``add_note(None, replace=True)``. A :exc:`TypeError`
+      is raise if ``note`` is neither a string nor ``None``.
 
-   .. versionadded:: 3.11
+      .. versionadded:: 3.11
+
+   .. attribute:: __notes__
+
+      A read-only field that contains a tuple of the notes of this exception.
+      See :meth:`add_note`.
+
+      .. versionadded:: 3.11
 
 
 .. exception:: Exception
@@ -898,7 +907,7 @@ their subgroups based on the types of the contained exceptions.
 
       The nesting structure of the current exception is preserved in the result,
       as are the values of its :attr:`message`, :attr:`__traceback__`,
-      :attr:`__cause__`, :attr:`__context__` and :attr:`__note__` fields.
+      :attr:`__cause__`, :attr:`__context__` and :attr:`__notes__` fields.
       Empty nested groups are omitted from the result.
 
       The condition is checked for all exceptions in the nested exception group,
@@ -915,7 +924,7 @@ their subgroups based on the types of the contained exceptions.
 
       Returns an exception group with the same :attr:`message`,
       :attr:`__traceback__`, :attr:`__cause__`, :attr:`__context__`
-      and :attr:`__note__` but which wraps the exceptions in ``excs``.
+      and :attr:`__notes__` but which wraps the exceptions in ``excs``.
 
       This method is used by :meth:`subgroup` and :meth:`split`. A
       subclass needs to override it in order to make :meth:`subgroup`

Include/cpython/pyerrors.h

@@ -6,7 +6,7 @@
 
 /* PyException_HEAD defines the initial segment of every exception class. */
 #define PyException_HEAD PyObject_HEAD PyObject *dict;\
-             PyObject *args; PyObject *note; PyObject *traceback;\
+             PyObject *args; PyObject *notes; PyObject *traceback;\
              PyObject *context; PyObject *cause;\
              char suppress_context;
 

Include/internal/pycore_global_strings.h

@@ -147,7 +147,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(__newobj__)
         STRUCT_FOR_ID(__newobj_ex__)
         STRUCT_FOR_ID(__next__)
-        STRUCT_FOR_ID(__note__)
+        STRUCT_FOR_ID(__notes__)
         STRUCT_FOR_ID(__or__)
         STRUCT_FOR_ID(__origin__)
         STRUCT_FOR_ID(__package__)

Include/internal/pycore_runtime_init.h

@@ -761,7 +761,7 @@ extern "C" {
                 INIT_ID(__newobj__), \
                 INIT_ID(__newobj_ex__), \
                 INIT_ID(__next__), \
-                INIT_ID(__note__), \
+                INIT_ID(__notes__), \
                 INIT_ID(__or__), \
                 INIT_ID(__origin__), \
                 INIT_ID(__package__), \

Lib/test/test_exception_group.py

@@ -502,7 +502,7 @@ def leaves(exc):
                 self.assertIs(eg.__cause__, part.__cause__)
                 self.assertIs(eg.__context__, part.__context__)
                 self.assertIs(eg.__traceback__, part.__traceback__)
-                self.assertIs(eg.__note__, part.__note__)
+                self.assertEqual(eg.__notes__, part.__notes__)
 
         def tbs_for_leaf(leaf, eg):
             for e, tbs in leaf_generator(eg):
@@ -567,7 +567,7 @@ def level3(i):
         try:
             nested_group()
         except ExceptionGroup as e:
-            e.__note__ = f"the note: {id(e)}"
+            e.add_note(f"the note: {id(e)}", replace=True)
             eg = e
 
         eg_template = [

Lib/test/test_exceptions.py

@@ -538,26 +538,40 @@ def testAttributes(self):
                                              'pickled "%r", attribute "%s' %
                                              (e, checkArgName))
 
-    def test_note(self):
+    def test_notes(self):
         for e in [BaseException(1), Exception(2), ValueError(3)]:
             with self.subTest(e=e):
-                self.assertIsNone(e.__note__)
-                e.__note__ = "My Note"
-                self.assertEqual(e.__note__, "My Note")
+                self.assertEqual(e.__notes__, ())
+                e.add_note("My Note")
+                self.assertEqual(e.__notes__, ("My Note",))
 
                 with self.assertRaises(TypeError):
-                    e.__note__ = 42
-                self.assertEqual(e.__note__, "My Note")
+                    e.add_note(42)
+                self.assertEqual(e.__notes__, ("My Note",))
 
-                e.__note__ = "Your Note"
-                self.assertEqual(e.__note__, "Your Note")
+                e.add_note("Your Note")
+                self.assertEqual(e.__notes__, ("My Note", "Your Note"))
 
-                with self.assertRaises(TypeError):
-                    del e.__note__
-                self.assertEqual(e.__note__, "Your Note")
+                with self.assertRaises(AttributeError):
+                    e.__notes__ = ("NewNote",)
+                self.assertEqual(e.__notes__, ("My Note", "Your Note"))
+
+                with self.assertRaises(AttributeError):
+                    del e.__notes__
+                self.assertEqual(e.__notes__, ("My Note", "Your Note"))
+
+                e.add_note("Our Note", replace=True)
+                self.assertEqual(e.__notes__, ("Our Note",))
+
+                e.add_note("Our Final Note", replace=False)
+                self.assertEqual(e.__notes__, ("Our Note", "Our Final Note"))
+
+                e.add_note(None, replace=False)
+                self.assertEqual(e.__notes__, ("Our Note", "Our Final Note"))
+
+                e.add_note(None, replace=True)
+                self.assertEqual(e.__notes__, ())
 
-                e.__note__ = None
-                self.assertIsNone(e.__note__)
 
     def testWithTraceback(self):
         try:

Lib/test/test_traceback.py

@@ -1326,18 +1326,38 @@ def test_exception_with_note(self):
         e = ValueError(42)
         vanilla = self.get_report(e)
 
-        e.__note__ = 'My Note'
+        e.add_note('My Note', replace=True)
         self.assertEqual(self.get_report(e), vanilla + 'My Note\n')
 
-        e.__note__ = ''
+        e.add_note('', replace=True)
         self.assertEqual(self.get_report(e), vanilla + '\n')
 
-        e.__note__ = 'Your Note'
+        e.add_note('Your Note', replace=True)
         self.assertEqual(self.get_report(e), vanilla + 'Your Note\n')
 
-        e.__note__ = None
+        e.add_note(None, replace=True)
         self.assertEqual(self.get_report(e), vanilla)
 
+    def test_exception_with_note_with_multiple_notes(self):
+        e = ValueError(42)
+        vanilla = self.get_report(e)
+
+        e.add_note('Note 1')
+        e.add_note('Note 2')
+        e.add_note('Note 3')
+
+        self.assertEqual(
+            self.get_report(e),
+            vanilla + 'Note 1\n' + 'Note 2\n' + 'Note 3\n')
+
+        e.add_note('Note 4', replace=True)
+        e.add_note('Note 5', replace=True)
+        e.add_note('Note 6')
+
+        self.assertEqual(
+            self.get_report(e),
+            vanilla + 'Note 5\n' + 'Note 6\n')
+
     def test_exception_qualname(self):
         class A:
             class B:
@@ -1688,16 +1708,16 @@ def exc():
                     try:
                         raise ValueError(msg)
                     except ValueError as e:
-                        e.__note__ = f'the {msg}'
+                        e.add_note(f'the {msg}')
                         excs.append(e)
                 raise ExceptionGroup("nested", excs)
             except ExceptionGroup as e:
-                e.__note__ = ('>> Multi line note\n'
-                              '>> Because I am such\n'
-                              '>> an important exception.\n'
-                              '>> empty lines work too\n'
-                              '\n'
-                              '(that was an empty line)')
+                e.add_note(('>> Multi line note\n'
+                            '>> Because I am such\n'
+                            '>> an important exception.\n'
+                            '>> empty lines work too\n'
+                            '\n'
+                            '(that was an empty line)'))
                 raise
 
         expected = (f'  + Exception Group Traceback (most recent call last):\n'
@@ -1733,6 +1753,64 @@ def exc():
         report = self.get_report(exc)
         self.assertEqual(report, expected)
 
+    def test_exception_group_with_multiple_notes(self):
+        def exc():
+            try:
+                excs = []
+                for msg in ['bad value', 'terrible value']:
+                    try:
+                        raise ValueError(msg)
+                    except ValueError as e:
+                        e.add_note(f'the {msg}')
+                        e.add_note(f'Goodbye {msg}')
+                        excs.append(e)
+                raise ExceptionGroup("nested", excs)
+            except ExceptionGroup as e:
+                e.add_note(('>> Multi line note\n'
+                            '>> Because I am such\n'
+                            '>> an important exception.\n'
+                            '>> empty lines work too\n'
+                            '\n'
+                            '(that was an empty line)'))
+                e.add_note('Goodbye!')
+                raise
+
+        expected = (f'  + Exception Group Traceback (most recent call last):\n'
+                    f'  |   File "{__file__}", line {self.callable_line}, in get_exception\n'
+                    f'  |     exception_or_callable()\n'
+                    f'  |     ^^^^^^^^^^^^^^^^^^^^^^^\n'
+                    f'  |   File "{__file__}", line {exc.__code__.co_firstlineno + 10}, in exc\n'
+                    f'  |     raise ExceptionGroup("nested", excs)\n'
+                    f'  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n'
+                    f'  | ExceptionGroup: nested\n'
+                    f'  | >> Multi line note\n'
+                    f'  | >> Because I am such\n'
+                    f'  | >> an important exception.\n'
+                    f'  | >> empty lines work too\n'
+                    f'  | \n'
+                    f'  | (that was an empty line)\n'
+                    f'  | Goodbye!\n'
+                    f'  +-+---------------- 1 ----------------\n'
+                    f'    | Traceback (most recent call last):\n'
+                    f'    |   File "{__file__}", line {exc.__code__.co_firstlineno + 5}, in exc\n'
+                    f'    |     raise ValueError(msg)\n'
+                    f'    |     ^^^^^^^^^^^^^^^^^^^^^\n'
+                    f'    | ValueError: bad value\n'
+                    f'    | the bad value\n'
+                    f'    | Goodbye bad value\n'
+                    f'    +---------------- 2 ----------------\n'
+                    f'    | Traceback (most recent call last):\n'
+                    f'    |   File "{__file__}", line {exc.__code__.co_firstlineno + 5}, in exc\n'
+                    f'    |     raise ValueError(msg)\n'
+                    f'    |     ^^^^^^^^^^^^^^^^^^^^^\n'
+                    f'    | ValueError: terrible value\n'
+                    f'    | the terrible value\n'
+                    f'    | Goodbye terrible value\n'
+                    f'    +------------------------------------\n')
+
+        report = self.get_report(exc)
+        self.assertEqual(report, expected)
+
 
 class PyExcReportingTests(BaseExceptionReportingTests, unittest.TestCase):
     #

Lib/traceback.py

@@ -689,7 +689,7 @@ def __init__(self, exc_type, exc_value, exc_traceback, *, limit=None,
         # Capture now to permit freeing resources: only complication is in the
         # unofficial API _format_final_exc_line
         self._str = _some_str(exc_value)
-        self.__note__ = exc_value.__note__ if exc_value else None
+        self.__notes__ = exc_value.__notes__ if exc_value else None
 
         if exc_type and issubclass(exc_type, SyntaxError):
             # Handle SyntaxError's specially
@@ -822,8 +822,9 @@ def format_exception_only(self):
             yield _format_final_exc_line(stype, self._str)
         else:
             yield from self._format_syntax_error(stype)
-        if self.__note__ is not None:
-            yield from [l + '\n' for l in self.__note__.split('\n')]
+        if self.__notes__ is not None:
+            for note in self.__notes__:
+                yield from [l + '\n' for l in note.split('\n')]
 
     def _format_syntax_error(self, stype):
         """Format SyntaxError exceptions (internal helper)."""