From 376c734216f54bb0f6676f60d0c771e24efe0824 Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Wed, 5 Jun 2024 14:02:52 +0200
Subject: [PATCH] [3.12] gh-119287: clarify doc on BaseExceptionGroup.derive
 and link to it from contextlib.suppress (GH-119657) (#120106)

gh-119287: clarify doc on BaseExceptionGroup.derive and link to it from contextlib.suppress (GH-119657)
(cherry picked from commit 5c02ea8bae2287a828840f5734966da23dc573dc)

Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
---
 Doc/library/contextlib.rst | 4 +++-
 Doc/library/exceptions.rst | 3 ++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index bad9da52d6a6ca..27cf99446e5980 100644
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -314,7 +314,9 @@ Functions and classes provided:
 
    If the code within the :keyword:`!with` block raises a
    :exc:`BaseExceptionGroup`, suppressed exceptions are removed from the
-   group.  If any exceptions in the group are not suppressed, a group containing them is re-raised.
+   group.  Any exceptions of the group which are not suppressed are re-raised in
+   a new group which is created using the original group's :meth:`~BaseExceptionGroup.derive`
+   method.
 
    .. versionadded:: 3.4
 
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 60600b2436b734..de46518e673763 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -967,7 +967,8 @@ their subgroups based on the types of the contained exceptions.
       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
+      This method is used by :meth:`subgroup` and :meth:`split`, which
+      are used in various contexts to break up an exception group. A
       subclass needs to override it in order to make :meth:`subgroup`
       and :meth:`split` return instances of the subclass rather
       than :exc:`ExceptionGroup`.