gh-89770: [PEP-678] add exception notes to tutorial (GH-30441)

diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst
index df4a38c955511b5dc8214d9bbbf1ba36693b4dec..796309c6cf0bb9eb96e0154058598be1fe639710 100644 (file)
--- 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:: __notes__
+
+      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
+
    .. attribute:: stack
 
       A :class:`StackSummary` representing the traceback.

diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst
index 01fd76283556ba790a526210a0d3f0bf906fd45c..57919e3bad132c9a8cf801894be2290785ca6cf1 100644 (file)
--- a/Doc/tutorial/errors.rst
+++ b/Doc/tutorial/errors.rst
@@ -559,3 +559,67 @@ 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 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')
+   ... except Exception as e:
+   ...     e.add_note('Add some information')
+   ...     e.add_note('Add some more information')
+   ...     raise
+   ...
+   Traceback (most recent call last):
+     File "<stdin>", line 2, in <module>
+   TypeError: bad type
+   Add some information
+   Add some more 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.add_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 "<stdin>", line 1, in <module>
+     | ExceptionGroup: We have some problems (3 sub-exceptions)
+     +-+---------------- 1 ----------------
+       | Traceback (most recent call last):
+       |   File "<stdin>", line 3, in <module>
+       |   File "<stdin>", line 2, in f
+       | OSError: operation failed
+       | Happened in Iteration 1
+       +---------------- 2 ----------------
+       | Traceback (most recent call last):
+       |   File "<stdin>", line 3, in <module>
+       |   File "<stdin>", line 2, in f
+       | OSError: operation failed
+       | Happened in Iteration 2
+       +---------------- 3 ----------------
+       | Traceback (most recent call last):
+       |   File "<stdin>", line 3, in <module>
+       |   File "<stdin>", line 2, in f
+       | OSError: operation failed
+       | Happened in Iteration 3
+       +------------------------------------
+   >>>