gh-99619: fix error in documentation of ExceptionGroup.derive() (GH-99621)

1 files changed, 27 insertions, 6 deletions

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 4271a30..1217b81 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -934,21 +934,42 @@ their subgroups based on the types of the contained exceptions.
 
    .. method:: derive(excs)
 
-      Returns an exception group with the same :attr:`message`,
-      :attr:`__traceback__`, :attr:`__cause__`, :attr:`__context__`
-      and :attr:`__notes__` but which wraps the exceptions in ``excs``.
+      Returns an exception group with the same :attr:`message`, 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`
       and :meth:`split` return instances of the subclass rather
-      than :exc:`ExceptionGroup`. ::
+      than :exc:`ExceptionGroup`.
+
+      :meth:`subgroup` and :meth:`split` copy the :attr:`__traceback__`,
+      :attr:`__cause__`, :attr:`__context__` and :attr:`__notes__` fields from
+      the original exception group to the one returned by :meth:`derive`, so
+      these fields do not need to be updated by :meth:`derive`. ::
 
          >>> class MyGroup(ExceptionGroup):
          ...     def derive(self, exc):
          ...         return MyGroup(self.message, exc)
          ...
-         >>> MyGroup("eg", [ValueError(1), TypeError(2)]).split(TypeError)
-         (MyGroup('eg', [TypeError(2)]), MyGroup('eg', [ValueError(1)]))
+         >>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
+         >>> e.add_note("a note")
+         >>> e.__context__ = Exception("context")
+         >>> e.__cause__ = Exception("cause")
+         >>> try:
+         ...    raise e
+         ... except Exception as e:
+         ...    exc = e
+         ...
+         >>> match, rest = exc.split(ValueError)
+         >>> exc, exc.__context__, exc.__cause__, exc.__notes__
+         (MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
+         >>> match, match.__context__, match.__cause__, match.__notes__
+         (MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
+         >>> rest, rest.__context__, rest.__cause__, rest.__notes__
+         (MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
+         >>> exc.__traceback__ is match.__traceback__ is rest.__traceback__
+         True
+
 
    Note that :exc:`BaseExceptionGroup` defines :meth:`__new__`, so
    subclasses that need a different constructor signature need to