Remove overrides of standard warning behaviour

[jakelishman]

Summary

Previously, qiskit attempted to override the deprecation warning filters
for internal qiskit code as soon as it was imported, so that they were
shown with the default filters. This isn't something we should be
doing; it's a user's choice, and it's unexpected that we would override
their settings in order to violate the normal Python behaviour. It also
had no effect on the tests, since test runners hook into the warnings
control at various times during the execution. If we do want to do
something similar, it would have been better to use
warnings.filterwarnings, instead of a private function.

The other change is to remove the "only warn once" filter from
qiskit.utils.deprecate_function. It's the default behaviour of Python
to only show one warning from each (category, message, module, line)
set, so users already shouldn't be too overwhelmed (and they should
change their code if they're seeing them anyway). Within the test
suite, it's important that all warnings are raised all the time, so we
can assert that deprecated calls warn and nothing else does; if things
only warn once, then the execution order of the tests matters for
correctness.

This should have no effect on the test suite as it stands right now,
because even one warning is enough to fail the entire run, and the
filtering behaviour was overridden by the runner anyway.

Details and comments

Having this will make it easier to put full warning assertions into the test suite (part of the solution to #6904). Currently, using self.assertWarns is unreliable if the cause is something decorated deprecate_function, because the "only warn once" behaviour means that sometimes the assertion will fail. It depends on execution order, whether it's in a ddt block, and a few other factors.

[levbishop]

I've been thinking to do this for some months, but you beat me to it. Thanks.

[jakelishman]

It's possible people have seen issues with too many warnings in the past because it can be a little mind-bending to set stacklevel correctly in warnings.warn, and we've not always got it right. When you do, Python should only display each "logical" triggering of a warning once. If you set the stack level too high (something we've done before), you may get more warnings than we'd like.

[levbishop]

Does this warrant a release note or something to advise users on how to make sure they learn about qiskit deprecations even outside of main? I agree its not really our place to fiddle with the filter, but some the extant behaviour does raise the probability these get seen

[jakelishman]

I could do a release note to highlight it, but I think for most users not much should actually change. Running in Jupyter will display deprecation warnings without the filter override.

The exception is if they're using a downstream package that depends on Qiskit and uses deprecated functionality, then they'll stop seeing warnings that weren't their fault. It's the downstream package's responsibility to run tests with deprecation warnings shown, and I think all major Python test runners immediately remove the "ignore" filter of deprecation warnings. I suppose they could also be missed if users are packaging up their own code into libraries that they're then calling from Jupyter, but I think we're better optimising the experience for people writing new code. People packaging up libraries should (in theory) know how to test them as well.

For example, here's the behaviour in Jupyter with #7212 (so Aer currently throws a warning on import, because it triggers a deprecation) but without this PR, i.e. the filter override is still in place:

Now with Python's default warning behaviour (i.e. with this PR), but the deprecation warning still being triggered by Aer shows

So the user still sees things that they're doing wrong, but doesn't get blamed for things we're doing wrong, which we should be catching in tests.

[jakelishman]

@levbishop: added release notes. It's not entirely an API change, but the "upgrade notes" section seemed like the best bet.

[levbishop]

I could do a release note to highlight it, but I think for most users not much should actually change. Running in Jupyter will display deprecation warnings without the filter override.

I take your point and this is the philosophy of the default filters. Nevertheless I'm sure a non-zero number of users have some kind of local package of functionality that they maintain, and import from it for their experimentation eg in jupyter, but this local package may be more a way to keep a few of their common workflows, not a fully-engineered solution with CI and test suite and so on, so they may miss deprecations.

Agreed that this is the users' responsibility to change the warning filter in this case (or deal with the consequences) but not all will do so....

[coveralls]

Pull Request Test Coverage Report for Build 1417954246

• 1 of 1 (100.0%) changed or added relevant line in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.0002%) to 82.318%

---

Totals
Change from base Build 1417605609:	-0.0002%
Covered Lines:	49270
Relevant Lines:	59853

---

💛 - Coveralls