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

[miss-islington]

https://github.com/python/cpython/commit/609273eb5277bbd635d0b9e101a76ac5578ca5f6
commit: 609273eb5277bbd635d0b9e101a76ac5578ca5f6
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-11-23T03:08:22-08:00
summary:

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

(cherry picked from commit 5d9183c7ad68eb9ddb53d54a3f9a27e29dbabf31)

Co-authored-by: Irit Katriel <1055913+iritkatriel at users.noreply.github.com>

files:
M Doc/library/exceptions.rst

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 4271a30de74a..1217b817b4e8 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