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

Wed Nov 23 05:59:58 EST 2022

https://github.com/python/cpython/commit/5d9183c7ad68eb9ddb53d54a3f9a27e29dbabf31
commit: 5d9183c7ad68eb9ddb53d54a3f9a27e29dbabf31
branch: main
author: Irit Katriel <1055913+iritkatriel at users.noreply.github.com>
committer: iritkatriel <1055913+iritkatriel at users.noreply.github.com>
date: 2022年11月23日T10:59:52Z
summary:
gh-99619: fix error in documentation of ExceptionGroup.derive() (GH-99621)
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
