raisesgroup followups

[jakkdl]

Followup to #13192, which got increasingly unwieldy towards the end so I'm going to do a couple followup PR's to clean up loose ends

• renames src/_pytest/raises_group.py to src/_pytest/raises.py
• moves pytest.raises from src/_pytest/python_api.py to src/_pytest/raises.py
• adds several newsfragments that should've been bundlen with add RaisesGroup & Matcher #13192
• add more detailed error message if you try to do RaisesGroup((ValueError, TypeError))
• spend way too much mental energy debating with myself if passing the wrong type to a function expecting an exception type is a TypeError or a ValueError, or if it matters at all

[Zac-HD]

looks good, but needs some merge fixes - consider rebasing?

[Zac-HD]

I think we really need to spell out this api, for people who aren't really familiar with Pytest. Something like

You can now pass :func:with pytest.raises(check=fn): <pytest.raises>, where fn is a function which takes a raised exception and returns a boolean. The test fails if no exception was raised (as usual with :func:pytest.raises), passes if an exception is raised and fn returns True, and re-raises the exception if fn returns False (which also fails the test).

[jakkdl]

I'm not sure the changelog needs to cater super hard to people not familiar with pytest at all, but agree it should be less technical. Though we no longer just reraise on fail, and made it clearer that it can be used in conjunction with the other parameters.

[bluetech]

Hi, I missed the previous episode of this so I hope you don't mind me asking a question late.

1. I don't see documentation for the new check parameter in the pytest.raises docstring. Unless I missed it, can it be added?

2. Would you mind briefly recounting to me the rationale for check? (Feel free to tell me to just go read the previous discussion...). Do I intuit correctly that it is not really meant to be used with the expected_exception overload, but with the 2nd overload when more elaborate logic is needed than just an isinstance?

[jakkdl]

Hi, I missed the previous episode of this so I hope you don't mind me asking a question late.

1. I don't see documentation for the new check parameter in the pytest.raises docstring. Unless I missed it, can it be added?

2. Would you mind briefly recounting to me the rationale for check? (Feel free to tell me to just go read the previous discussion...). Do I intuit correctly that it is not really meant to be used with the expected_exception overload, but with the 2nd overload when more elaborate logic is needed than just an isinstance?

1. done! ... and added a bunch of :param stuff to the docstrings. Though these could be improved even more tbh, and it's unclear if RaisesExc needs a docstring at all or if it should just refer to raises ... and oh goodness I'm starting to reconsider my position on raises_group now that with RaisesGroup(raises(ValueError, match="hi")) is possible
2. check is a very general tool that can be used for a lot of things, and there's valid uses both with and without the other params, but the example in the docstring was pretty awful. You can do lots of stuff with it: inspecting __context__ and/or __cause__ (Match causing exceptions with pytest.raises #12763), doing a type check with is instead of isinstance, checking a OSError.errno, basically anything that you previously would require checking afterwards by inspecting ExcInfo.
   Likely not required in the basic pytest.raises case, although it might be slightly cleaner to have everything in one place

with pytest.raises(OSError, check=lambda e: e.errno == errno.EINVAL):
   ...
# versus
with pytest.raises(OSError) as excinfo:
   ...
assert excinfo.value.errno == errno.EINVAL

but for the RaisesGroup case it becomes required in some tricky cases with lots of different exceptions, and/or cleans it up significantly not having to check against excinfo.value.exceptions[0].exceptions[0].__cause__ is xxx etc