gh-103791: Make contextlib.suppress also act on exceptions within an ExceptionGroup (#103792)

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

Doc/library/contextlib.rst

@@ -304,8 +304,15 @@ Functions and classes provided:
 
    This context manager is :ref:`reentrant <reentrant-cms>`.
 
+   If the code within the :keyword:`!with` block raises an
+   :exc:`ExceptionGroup`, suppressed exceptions are removed from the
+   group.  If any exceptions in the group are not suppressed, a group containing them is re-raised.
+
    .. versionadded:: 3.4
 
+   .. versionchanged:: 3.12
+      ``suppress`` now supports suppressing exceptions raised as
+      part of an :exc:`ExceptionGroup`.
 
 .. function:: redirect_stdout(new_target)
 

Lib/contextlib.py

@@ -441,7 +441,16 @@ class suppress(AbstractContextManager):
         # exactly reproduce the limitations of the CPython interpreter.
         #
         # See http://bugs.python.org/issue12029 for more details
-        return exctype is not None and issubclass(exctype, self._exceptions)
+        if exctype is None:
+            return
+        if issubclass(exctype, self._exceptions):
+            return True
+        if issubclass(exctype, ExceptionGroup):
+            match, rest = excinst.split(self._exceptions)
+            if rest is None:
+                return True
+            raise rest
+        return False
 
 
 class _BaseExitStack:

Lib/test/support/testcase.py

@@ -0,0 +1,25 @@
+class ExceptionIsLikeMixin:
+    def assertExceptionIsLike(self, exc, template):
+        """
+        Passes when the provided `exc` matches the structure of `template`.
+        Individual exceptions don't have to be the same objects or even pass
+        an equality test: they only need to be the same type and contain equal
+        `exc_obj.args`.
+        """
+        if exc is None and template is None:
+            return
+
+        if template is None:
+            self.fail(f"unexpected exception: {exc}")
+
+        if exc is None:
+            self.fail(f"expected an exception like {template!r}, got None")
+
+        if not isinstance(exc, ExceptionGroup):
+            self.assertEqual(exc.__class__, template.__class__)
+            self.assertEqual(exc.args[0], template.args[0])
+        else:
+            self.assertEqual(exc.message, template.message)
+            self.assertEqual(len(exc.exceptions), len(template.exceptions))
+            for e, t in zip(exc.exceptions, template.exceptions):
+                self.assertExceptionIsLike(e, t)

Lib/test/test_contextlib.py

@@ -10,6 +10,7 @@ import unittest
 from contextlib import *  # Tests __all__
 from test import support
 from test.support import os_helper
+from test.support.testcase import ExceptionIsLikeMixin
 import weakref
 
 
@@ -1148,7 +1149,7 @@ class TestRedirectStderr(TestRedirectStream, unittest.TestCase):
     orig_stream = "stderr"
 
 
-class TestSuppress(unittest.TestCase):
+class TestSuppress(ExceptionIsLikeMixin, unittest.TestCase):
 
     @support.requires_docstrings
     def test_instance_docs(self):
@@ -1202,6 +1203,30 @@ class TestSuppress(unittest.TestCase):
             1/0
         self.assertTrue(outer_continued)
 
+    def test_exception_groups(self):
+        eg_ve = lambda: ExceptionGroup(
+            "EG with ValueErrors only",
+            [ValueError("ve1"), ValueError("ve2"), ValueError("ve3")],
+        )
+        eg_all = lambda: ExceptionGroup(
+            "EG with many types of exceptions",
+            [ValueError("ve1"), KeyError("ke1"), ValueError("ve2"), KeyError("ke2")],
+        )
+        with suppress(ValueError):
+            raise eg_ve()
+        with suppress(ValueError, KeyError):
+            raise eg_all()
+        with self.assertRaises(ExceptionGroup) as eg1:
+            with suppress(ValueError):
+                raise eg_all()
+        self.assertExceptionIsLike(
+            eg1.exception,
+            ExceptionGroup(
+                "EG with many types of exceptions",
+                [KeyError("ke1"), KeyError("ke2")],
+            ),
+        )
+
 
 class TestChdir(unittest.TestCase):
     def make_relative_path(self, *parts):

Lib/test/test_except_star.py

@@ -1,6 +1,7 @@
 import sys
 import unittest
 import textwrap
+from test.support.testcase import ExceptionIsLikeMixin
 
 class TestInvalidExceptStar(unittest.TestCase):
     def test_mixed_except_and_except_star_is_syntax_error(self):
@@ -169,26 +170,7 @@ class TestBreakContinueReturnInExceptStarBlock(unittest.TestCase):
         self.assertIsInstance(exc, ExceptionGroup)
 
 
-class ExceptStarTest(unittest.TestCase):
-    def assertExceptionIsLike(self, exc, template):
-        if exc is None and template is None:
-            return
-
-        if template is None:
-            self.fail(f"unexpected exception: {exc}")
-
-        if exc is None:
-            self.fail(f"expected an exception like {template!r}, got None")
-
-        if not isinstance(exc, ExceptionGroup):
-            self.assertEqual(exc.__class__, template.__class__)
-            self.assertEqual(exc.args[0], template.args[0])
-        else:
-            self.assertEqual(exc.message, template.message)
-            self.assertEqual(len(exc.exceptions), len(template.exceptions))
-            for e, t in zip(exc.exceptions, template.exceptions):
-                self.assertExceptionIsLike(e, t)
-
+class ExceptStarTest(ExceptionIsLikeMixin, unittest.TestCase):
     def assertMetadataEqual(self, e1, e2):
         if e1 is None or e2 is None:
             self.assertTrue(e1 is None and e2 is None)

Misc/NEWS.d/next/Library/2023-04-24-23-07-56.gh-issue-103791.bBPWdS.rst

@@ -0,0 +1,3 @@
+:class:`contextlib.suppress` now supports suppressing exceptions raised as
+part of an :exc:`ExceptionGroup`. If other exceptions exist on the group, they
+are re-raised in a group that does not contain the suppressed exceptions.