Kyle Stanley wrote:
Hmm, I think we may benefit from focusing the efforts on this point (at least at first), particularly with regards to making the official documentation for the warnings module [1] easier to understand with some more examples, or perhaps writing a warnings HOWTO guide [2], which could include the correct way to add filters for specific warning types by module for a significant number of different filters.
Adding *more* documentation can easily make the problem worse in some ways. We're dealing with the very tricky problem of directing and sustaining attention.
When warnings are displayed, they show the filename, but filters require a module name, and converting between the two is tedious.
I could see it being useful to have a utility for filtering warnings by filename rather than just module, if it's reasonably possible to implement.
Filtering by an exact filename wouldn't work for code that's meant to run on multiple systems. Filtering by some kind of pattern could maybe work, but brings in new problems.
The more warnings there are, and thus the more serious the need to filter them properly, the more work it is to write all the filters.
This could be potentially addressed by adding an example in the warning docs or a new warnings HOWTO that includes something along the lines of the following: modules_to_filter = {"foo": ResourceWarning, "bar": DeprecationWarning} for mod, cat in modules_to_filter.items(): warnings.filterwarnings("ignore", category=cat, module=mod)
(I suspect the actual documented example would be much more fleshed out and explained, the above was very quickly thrown together as a rough example) Alternatively, we could consider adding a helper function to the warnings module for adding a filter with the same action and warning category across multiple modules at once; by accepting a collection of a strings instead of a single string (like filterwarnings() does for it's module parameter).
This doesn't really help. It's already easy to copy and paste `warnings.filterwarnings("ignore", module="", category=)` ten times. And people know how to write a loop. It's the process of extracting categories and module names that requires work either way.
I propose we add a built in mechanism that is easy to use and remember which displays Python code that can be copy pasted. I really don't like the idea of a builtin that specifically revolves around the expectation of its output being copied and pasted as code elsewhere, particularly from an API design perspective.
Can you elaborate on the problem? There's already catch_warnings to collect data.
Also, if we were to consider something like this, it seems more appropriate to be included in the warnings module rather than as a builtin.
Sorry, to clarify, by "built in mechanism" I meant any interface (not necessarily a function) that doesn't require installing an external tool. A function would definitely be in the warnings module.
+1 on the general idea of making the process of correctly adding a decent volume of warning filters more clear.
The problem here is not knowledge, it's effort. All these obstacles are not that hard to get past, but they make lazier choices more tempting. Most users will therefore either: 1. Not filter warnings at all, thus making it harder to notice genuinely important warnings. 2. Filter too many warnings because that's so much easier. This in turn can make API designers reluctant to add important warnings because of the potential impact on their users. At worst their users will be harmed by not seeing other important warnings. At best they will be annoyed either by constantly seeing warnings or by the effort of hiding them properly. I'm saying that the correct way to do things should be as easy and frictionless as possible, so that by default it's the first thing users want to do. Then warnings can become exactly as obtrusive as they're meant to be. A single function that can be found via autocomplete and requires no arguments is really easy, and calling it would be the hardest step.