Improve pytest.warns() docs to clarify difference with catch_warnings()

[nicoddemus]

We should add some stdlib links to the relevant docs:

• If you want to get a list of warnings, but no error if no warnings were emitted, use warnings.catch_warnings()
• To say "any warning here is unexpected / an error", use with catch_warnings(): simplefilter("error"); ...

I didn't intend to break anything, but nor did I consider that people might be using pytest.warns() like warnings.catch_warnings(). My apologies for the inconvenience!

Originally posted by @Zac-HD in #8677 (comment)

[Zac-HD]

Per #9386 we should also expand the deprecation message to suggest use of stdlib catch_warnings() for cases where you either allow or expect no warnings to be emitted.

[The-Compiler]

I wonder if we should instead provide some kind of pytest convenience API for this case, though? I imagine something like pytest.warns(optional=True) or perhaps pytest.warns(raising=False). This would make it a bit easier for people to migrate and probably also make our deprecation guide simpler.

[WarrenWeckesser]

FYI: We need to replace a few occurrences of pytest.warns(None) in the SciPy tests (see scipy/scipy#15186), and we observe the same issue as noted in #9386: pytest.warns() in 7.0.0rc1 does not work the same as pytest.warns(None) in 6.2.5, so the message in the deprecation warning is a bit misleading.

[bashtage]

It would be very helpful if the best way to handle runtime-dependent warnings is documented. In a nutshell, we have parameterized tests that warn under some parameterizations and do not warn under others. We have been using something like

expected_warn = FutureWarning if param == "n" else None
with pytest.warns(expected_warn):
    ...

This worked in the sense that it would ensure that FutureWarning was raised when it should even if it silenced any warning otherwise, and so was not strict.

What is the best way to handle a situation like this? I had thought of

expected_warn = [FutureWarning] if param == "n" else []
with pytest.warns(*expected_warn):
    ...

but it seems a bit unnatural, and I'm not even sure this would work given this thread and others.

[nicoddemus]

Please see #9404.

[nicoddemus]

Fixed by #9495