Add support to testing.RaisesGroup for catching unwrapped exceptions

docs/source/conf.py

@@ -21,6 +21,7 @@
 import collections.abc
 import os
 import sys
+import types
 from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
@@ -98,14 +99,22 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-process-signature
 def autodoc_process_signature(
     app: Sphinx,
-    what: object,
+    what: str,
     name: str,
     obj: object,
     options: object,
     signature: str,
     return_annotation: str,
 ) -> tuple[str, str]:
     """Modify found signatures to fix various issues."""
+    if name == "trio.testing._raises_group._ExceptionInfo.type":
+        # This has the type "type[E]", which gets resolved into the property itself.
+        # That means Sphinx can't resolve it. Fix the issue by overwriting with a fully-qualified
+        # name.
+        assert isinstance(obj, property), obj
+        assert isinstance(obj.fget, types.FunctionType), obj.fget
+        assert obj.fget.__annotations__["return"] == "type[E]", obj.fget.__annotations__
+        obj.fget.__annotations__["return"] = "type[~trio.testing._raises_group.E]"
     if signature is not None:
         signature = signature.replace("~_contextvars.Context", "~contextvars.Context")
         if name == "trio.lowlevel.RunVar":  # Typevar is not useful here.
@@ -114,6 +123,13 @@ def autodoc_process_signature(
             # Strip the type from the union, make it look like = ...
             signature = signature.replace(" | type[trio._core._local._NoValue]", "")
             signature = signature.replace("<class 'trio._core._local._NoValue'>", "...")
+        if (
+            name in ("trio.testing.RaisesGroup", "trio.testing.Matcher")
+            and "+E" in signature
+        ):
+            # This typevar being covariant isn't handled correctly in some cases, strip the +
+            # and insert the fully-qualified name.
+            signature = signature.replace("+E", "~trio.testing._raises_group.E")
         if "DTLS" in name:
             signature = signature.replace("SSL.Context", "OpenSSL.SSL.Context")
         # Don't specify PathLike[str] | PathLike[bytes], this is just for humans.

newsfragments/2989.bugfix.rst

@@ -0,0 +1 @@
+Fixed a bug where :class:`trio.testing.RaisesGroup(..., strict=False) <trio.testing.RaisesGroup>` would check the number of exceptions in the raised `ExceptionGroup` before flattening subgroups, leading to incorrectly failed matches.

newsfragments/2989.deprecated.rst

@@ -0,0 +1 @@
+Deprecated ``strict`` parameter from :class:`trio.testing.RaisesGroup`, previous functionality of ``strict=False`` is now in ``flatten_subgroups=True``.

newsfragments/2989.feature.rst

@@ -0,0 +1 @@
+:class:`trio.testing.RaisesGroup` can now catch an unwrapped exception with ``unwrapped=True``. This means that the behaviour of :ref:`except* <except_star>` can be fully replicated in combination with ``flatten_subgroups=True`` (formerly ``strict=False``)

src/trio/_tests/test_testing_raisesgroup.py

@@ -78,33 +78,77 @@
         with RaisesGroup(ValueError, SyntaxError):
             raise ExceptionGroup("", (ValueError(),))
 
+
+def test_flatten_subgroups() -> None:
     # loose semantics, as with expect*
-    with RaisesGroup(ValueError, strict=False):
+    with RaisesGroup(ValueError, flatten_subgroups=True):
         raise ExceptionGroup("", (ExceptionGroup("", (ValueError(),)),))
 
+    with RaisesGroup(ValueError, TypeError, flatten_subgroups=True):
+        raise ExceptionGroup("", (ExceptionGroup("", (ValueError(), TypeError())),))
+    with RaisesGroup(ValueError, TypeError, flatten_subgroups=True):
+        raise ExceptionGroup("", [ExceptionGroup("", [ValueError()]), TypeError()])
+
     # mixed loose is possible if you want it to be at least N deep
-    with RaisesGroup(RaisesGroup(ValueError, strict=False)):
+    with RaisesGroup(RaisesGroup(ValueError, flatten_subgroups=True)):
         raise ExceptionGroup("", (ExceptionGroup("", (ValueError(),)),))
-    with RaisesGroup(RaisesGroup(ValueError, strict=False)):
+    with RaisesGroup(RaisesGroup(ValueError, flatten_subgroups=True)):
         raise ExceptionGroup(
             "", (ExceptionGroup("", (ExceptionGroup("", (ValueError(),)),)),)
         )
     with pytest.raises(ExceptionGroup):
-        with RaisesGroup(RaisesGroup(ValueError, strict=False)):
+        with RaisesGroup(RaisesGroup(ValueError, flatten_subgroups=True)):
             raise ExceptionGroup("", (ValueError(),))
 
     # but not the other way around
     with pytest.raises(
         ValueError,
-        match="^You cannot specify a nested structure inside a RaisesGroup with strict=False$",
+        match="^You cannot specify a nested structure inside a RaisesGroup with",
     ):
-        RaisesGroup(RaisesGroup(ValueError), strict=False)
+        RaisesGroup(RaisesGroup(ValueError), flatten_subgroups=True)
+
 
-    # currently not fully identical in behaviour to expect*, which would also catch an unwrapped exception
+def test_catch_unwrapped_exceptions() -> None:
+    # Catches lone exceptions with strict=False
+    # just as except* would
+    with RaisesGroup(ValueError, allow_unwrapped=True):
+        raise ValueError
+
+    # expecting multiple unwrapped exceptions is not possible
+    with pytest.raises(
+        ValueError, match="^You cannot specify multiple exceptions with"
+    ):
+        with RaisesGroup(SyntaxError, ValueError, allow_unwrapped=True):
+            ...
+    # if users want one of several exception types they need to use a Matcher
+    # (which the error message suggests)
+    with RaisesGroup(
+        Matcher(check=lambda e: isinstance(e, (SyntaxError, ValueError))),
+        allow_unwrapped=True,
+    ):
+        raise ValueError
+
+    # Unwrapped nested `RaisesGroup` is likely a user error, so we raise an error.
+    with pytest.raises(ValueError, match="has no effect when expecting"):
+        with RaisesGroup(RaisesGroup(ValueError), allow_unwrapped=True):
+            ...
+    # But it *can* be used to check for nesting level +- 1 if they move it to
+    # the nested RaisesGroup. Users should probably use `Matcher`s instead though.
+    with RaisesGroup(RaisesGroup(ValueError, allow_unwrapped=True)):
+        raise ExceptionGroup("", [ExceptionGroup("", [ValueError()])])
+    with RaisesGroup(RaisesGroup(ValueError, allow_unwrapped=True)):
+        raise ExceptionGroup("", [ValueError()])
+
+    # with allow_unwrapped=False (default) it will not be caught
     with pytest.raises(ValueError, match="^value error text$"):
-        with RaisesGroup(ValueError, strict=False):
+        with RaisesGroup(ValueError):
             raise ValueError("value error text")
 
+    # code coverage
+    with pytest.raises(TypeError):
+        with RaisesGroup(ValueError, allow_unwrapped=True):
+            raise TypeError
+
 
 def test_match() -> None:
     # supports match string
@@ -260,3 +304,12 @@
     assert excinfo.type is ExceptionGroup
     assert excinfo.value.exceptions[0].args == ("hello",)
     assert isinstance(excinfo.tb, TracebackType)
+
+
+def test_deprecated_strict() -> None:
+    """`strict` has been replaced with `flatten_subgroups`"""
+    # parameter is typed as `None` to also emit a type error if passing anything
+    with pytest.deprecated_call():
+        RaisesGroup(ValueError, strict=False)  # type: ignore[arg-type]
+    with pytest.deprecated_call():
+        RaisesGroup(ValueError, strict=True)  # type: ignore[arg-type]

src/trio/_tests/type_tests/raisesgroup.py

@@ -33,12 +33,7 @@ def check_inheritance_and_assignments() -> None:
 
     a: BaseExceptionGroup[BaseExceptionGroup[ValueError]]
     a = RaisesGroup(RaisesGroup(ValueError))
-    # pyright-ignore due to bug in exceptiongroup
-    # https://github.com/agronholm/exceptiongroup/pull/101
-    # once fixed we'll get errors for unnecessary-pyright-ignore and can clean up
-    a = BaseExceptionGroup(
-        "", (BaseExceptionGroup("", (ValueError(),)),)  # pyright: ignore
-    )
+    a = BaseExceptionGroup("", (BaseExceptionGroup("", (ValueError(),)),))
     assert a
 
 
@@ -71,23 +66,25 @@ def check_matcher_init() -> None:
     def check_exc(exc: BaseException) -> bool:
         return isinstance(exc, ValueError)
 
-    def check_filenotfound(exc: FileNotFoundError) -> bool:
-        return not exc.filename.endswith(".tmp")
-
     # Check various combinations of constructor signatures.
-    # At least 1 arg must be provided. If exception_type is provided, that narrows
-    # check's argument.
+    # At least 1 arg must be provided.
     Matcher()  # type: ignore
     Matcher(ValueError)
     Matcher(ValueError, "regex")
     Matcher(ValueError, "regex", check_exc)
     Matcher(exception_type=ValueError)
     Matcher(match="regex")
     Matcher(check=check_exc)
-    Matcher(check=check_filenotfound)  # type: ignore
     Matcher(ValueError, match="regex")
-    Matcher(FileNotFoundError, check=check_filenotfound)
     Matcher(match="regex", check=check_exc)
+
+    def check_filenotfound(exc: FileNotFoundError) -> bool:
+        return not exc.filename.endswith(".tmp")
+
+    # If exception_type is provided, that narrows the `check` method's argument.
+    Matcher(FileNotFoundError, check=check_filenotfound)
+    Matcher(ValueError, check=check_filenotfound)  # type: ignore
+    Matcher(check=check_filenotfound)  # type: ignore
     Matcher(FileNotFoundError, match="regex", check=check_filenotfound)
 
 
@@ -125,12 +122,34 @@ def check_nested_raisesgroups_contextmanager() -> None:
 
 def check_nested_raisesgroups_matches() -> None:
     """Check nested RaisesGroups with .matches"""
-    # pyright-ignore due to bug in exceptiongroup
-    # https://github.com/agronholm/exceptiongroup/pull/101
-    # once fixed we'll get errors for unnecessary-pyright-ignore and can clean up
     exc: ExceptionGroup[ExceptionGroup[ValueError]] = ExceptionGroup(
-        "", (ExceptionGroup("", (ValueError(),)),)  # pyright: ignore
+        "", (ExceptionGroup("", (ValueError(),)),)
     )
     # has the same problems as check_nested_raisesgroups_contextmanager
     if RaisesGroup(RaisesGroup(ValueError)).matches(exc):
         assert_type(exc, BaseExceptionGroup[RaisesGroup[ValueError]])
+
+
+def check_multiple_exceptions_1() -> None:
+    a = RaisesGroup(ValueError, ValueError)
+    b = RaisesGroup(Matcher(ValueError), Matcher(ValueError))
+    c = RaisesGroup(ValueError, Matcher(ValueError))
+
+    d: BaseExceptionGroup[ValueError]
+    d = a
+    d = b
+    d = c
+    assert d
+
+
+def check_multiple_exceptions_2() -> None:
+    # This previously failed due to lack of covariance in the TypeVar
+    a = RaisesGroup(Matcher(ValueError), Matcher(TypeError))
+    b = RaisesGroup(Matcher(ValueError), TypeError)
+    c = RaisesGroup(ValueError, TypeError)
+
+    d: BaseExceptionGroup[Exception]
+    d = a
+    d = b
+    d = c
+    assert d