Deprecate testing.RaisesGroup and testing.Matcher (#3337)

* chore: deprecate `RaisesGroup`

* feat: deprecate `RaisesGroup` using `deprecate_attributes` utility

* feat: deprecate `Matcher`

* feat: make `DeprecatedAttribute` as `final`

* feat: supress warnings about deprecation warning on specific test cases

* fix: replace RaisesGroup & Matcher with pytest alternatives across all test cases

* docs: add newsfragment

* fix: change version number

* style: format merged code

* fix: adjust `test_static_tool_sees_class_members` for deprecated classes (RaisesGroup, Matcher)

* fix: change text formatting, so that build tool won't search for references

* fix: add underscore prefix on class names to match exported classes' names

* style: correct formatting on newsfragment

* fix: find/replace

* fix: use `pytest.deprecated_call` context manager

* fix: delete type tests, mypy errors

* fix: remove deprecated calls

* chore: update `_check_type_completeness.json`

* test: add test case to test deprecation

Author: AbduazizZiyodov

newsfragments/3326.deprecated.rst

@@ -0,0 +1 @@
+Both :class:`trio.testing.RaisesGroup` and :class:`trio.testing.Matcher` have been deprecated. Pytest alternatives ``pytest.RaisesGroup`` and ``pytest.RaisesExc`` (respectively) are considered correct replacement.

src/trio/_core/_tests/test_cancelled.py

@@ -7,7 +7,7 @@
 import trio
 from trio import Cancelled
 from trio.lowlevel import current_task
-from trio.testing import RaisesGroup, wait_all_tasks_blocked
+from trio.testing import wait_all_tasks_blocked
 
 from .test_ki import ki_self
 
@@ -108,7 +108,7 @@ async def failing_task(task_status: trio.TaskStatus[trio.lowlevel.Task]) -> None
         task_status.started(current_task())
         raise ValueError
 
-    with RaisesGroup(ValueError, TypeError):
+    with pytest.RaisesGroup(ValueError, TypeError):
         async with trio.open_nursery() as nursery:
             fail_task = await nursery.start(failing_task)
             with pytest.raises(Cancelled, match=match_str.format(fail_task)):
@@ -123,7 +123,7 @@ async def failing_task(task_status: trio.TaskStatus[trio.lowlevel.Task]) -> None
         await wait_all_tasks_blocked()
         raise ValueError
 
-    with RaisesGroup(ValueError, TypeError):
+    with pytest.RaisesGroup(ValueError, TypeError):
         async with trio.open_nursery() as nursery:
             fail_task = await nursery.start(failing_task)
             await nursery.start(cancelled_task, fail_task)
@@ -147,7 +147,7 @@ async def cancelled_task() -> None:
         ):
             await trio.sleep_forever()
 
-    with RaisesGroup(ValueError):
+    with pytest.RaisesGroup(ValueError):
         async with trio.open_nursery() as nursery:
             nursery.start_soon(cancelled_task)
             await wait_all_tasks_blocked()
@@ -192,7 +192,7 @@ async def child() -> None:
         ):
             await trio.sleep_forever()
 
-    with RaisesGroup(ValueError):
+    with pytest.RaisesGroup(ValueError):
         async with trio.open_nursery() as nursery:
             nursery.start_soon(child)
             await ev.wait()
@@ -214,7 +214,7 @@ async def sleeper(name: str) -> None:
     async def raiser(name: str) -> None:
         ki_self()
 
-    with RaisesGroup(KeyboardInterrupt):
+    with pytest.RaisesGroup(KeyboardInterrupt):
         async with trio.open_nursery() as nursery:
             nursery.start_soon(sleeper, "s1")
             nursery.start_soon(sleeper, "s2")

src/trio/_core/_tests/test_ki.py

@@ -12,8 +12,6 @@
 import outcome
 import pytest
 
-from trio.testing import RaisesGroup
-
 from .tutil import gc_collect_harder
 
 try:
@@ -309,7 +307,7 @@ async def check_unprotected_kill() -> None:
             nursery.start_soon(raiser, "r1", record_set)
 
     # raises inside a nursery, so the KeyboardInterrupt is wrapped in an ExceptionGroup
-    with RaisesGroup(KeyboardInterrupt):
+    with pytest.RaisesGroup(KeyboardInterrupt):
         _core.run(check_unprotected_kill)
     assert record_set == {"s1 ok", "s2 ok", "r1 raise ok"}
 
@@ -326,7 +324,7 @@ async def check_protected_kill() -> None:
             # __aexit__ blocks, and then receives the KI
 
     # raises inside a nursery, so the KeyboardInterrupt is wrapped in an ExceptionGroup
-    with RaisesGroup(KeyboardInterrupt):
+    with pytest.RaisesGroup(KeyboardInterrupt):
         _core.run(check_protected_kill)
     assert record_set == {"s1 ok", "s2 ok", "r1 cancel ok"}
 

src/trio/_core/_tests/test_parking_lot.py

@@ -11,7 +11,6 @@
     current_task,
     remove_parking_lot_breaker,
 )
-from trio.testing import Matcher, RaisesGroup
 
 from ... import _core
 from ...testing import wait_all_tasks_blocked
@@ -267,8 +266,8 @@ async def bad_parker(lot: ParkingLot, scope: _core.CancelScope) -> None:
     cs = _core.CancelScope()
 
     # check that parked task errors
-    with RaisesGroup(
-        Matcher(_core.BrokenResourceError, match="^Parking lot broken by"),
+    with pytest.RaisesGroup(
+        pytest.RaisesExc(_core.BrokenResourceError, match="^Parking lot broken by"),
     ):
         async with _core.open_nursery() as nursery:
             nursery.start_soon(bad_parker, lot, cs)
@@ -382,8 +381,8 @@ async def return_me_and_park(
         await lot.park()
 
     lot = ParkingLot()
-    with RaisesGroup(
-        Matcher(_core.BrokenResourceError, match="^Parking lot broken by"),
+    with pytest.RaisesGroup(
+        pytest.RaisesExc(_core.BrokenResourceError, match="^Parking lot broken by"),
     ):
         async with _core.open_nursery() as nursery:
             child_task = await nursery.start(return_me_and_park, lot)