gh-89770: Implement PEP-678 - Exception notes

Doc/library/exceptions.rst

@@ -126,13 +126,20 @@ 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)
 
-      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.
+      Add the string ``note`` to the exception's notes which appear in the standard
+      traceback after the exception string. A :exc:`TypeError` is raise if ``note``
+      is not a string.
 
-   .. versionadded:: 3.11
+      .. versionadded:: 3.11
+
+   .. attribute:: __notes__
+
+      A tuple of the notes of this exception, which were added with :meth:`add_note`.
+      Its contents can be cleared with ``del e.__notes__``.
+
+      .. versionadded:: 3.11
 
 
 .. exception:: Exception
@@ -898,7 +905,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 +922,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,9 @@ 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(
+                    getattr(eg, '__notes__', None),
+                    getattr(part, '__notes__', None))
 
         def tbs_for_leaf(leaf, eg):
             for e, tbs in leaf_generator(eg):
@@ -567,7 +569,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)}")
             eg = e
 
         eg_template = [

Lib/test/test_exceptions.py

@@ -538,26 +538,28 @@ 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.assertFalse(hasattr(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")
+                del e.__notes__
+                self.assertFalse(hasattr(e, '__notes__'))
+
+                e.add_note("Our Note")
+                self.assertEqual(e.__notes__, ["Our Note"])
 
-                e.__note__ = None
-                self.assertIsNone(e.__note__)
+                e.__notes__ = 42
+                self.assertEqual(e.__notes__, 42)
 
     def testWithTraceback(self):
         try:

Lib/test/test_traceback.py

@@ -1326,18 +1326,50 @@ def test_exception_with_note(self):
         e = ValueError(42)
         vanilla = self.get_report(e)
 
-        e.__note__ = 'My Note'
+        e.add_note('My Note')
         self.assertEqual(self.get_report(e), vanilla + 'My Note\n')
 
-        e.__note__ = ''
+        del e.__notes__
+        e.add_note('')
         self.assertEqual(self.get_report(e), vanilla + '\n')
 
-        e.__note__ = 'Your Note'
+        del e.__notes__
+        e.add_note('Your Note')
         self.assertEqual(self.get_report(e), vanilla + 'Your Note\n')
 
-        e.__note__ = None
+        del e.__notes__
         self.assertEqual(self.get_report(e), vanilla)
 
+        # non-sequence __notes__ is ignored
+        e.__notes__ = 42
+        self.assertEqual(self.get_report(e), vanilla)
+
+        # non-string items in the __notes__ sequence are ignored
+        e.__notes__  = [42, 'Final Note']
+        self.assertEqual(self.get_report(e), vanilla + 'Final Note\n')
+
+    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')
+
+        del e.__notes__
+        e.add_note('Note 4')
+        del e.__notes__
+        e.add_note('Note 5')
+        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 +1720,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 +1765,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

@@ -1,6 +1,6 @@
 """Extract, format and print information about Python stack traces."""
 
-import collections
+import collections.abc
 import itertools
 import linecache
 import sys
@@ -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__ = getattr(exc_value, '__notes__', None)
 
         if exc_type and issubclass(exc_type, SyntaxError):
             # Handle SyntaxError's specially
@@ -822,8 +822,10 @@ 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 isinstance(self.__notes__, collections.abc.Sequence):
+            for note in self.__notes__:
+                if isinstance(note, str):
+                    yield from [l + '\n' for l in note.split('\n')]
 
     def _format_syntax_error(self, stype):
         """Format SyntaxError exceptions (internal helper)."""