> 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.
Improving the existing docs doesn't necessarily mean adding more in terms to length or total content, even if an example or two were added. Often times a significant documentation improvement can result in less total characters.
> 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'm not arguing that the example covers anything remotely involved or complex, but based on your initial statement regarding it being hard to find out how to properly ignore by a specific warning category and module in general, it seemed like a step in the right direction.
> Can you elaborate on the problem? There's already catch_warnings to collect data.
> 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.
Ah, I see. We typically refer to "built in" or "builtins" as specifically being a member of the "builtins" module (which includes the builtin functions and constants). A member that can be accessed without requiring the installation of any external tools would typically be referred to as a member of the standard library.
Describing a member that can be accessed without external tools as a "built in mechanism" isn't really wrong since it's effectively a "built in mechanism" to CPython, but it might be a bit confusing though (particularly on here and python-dev).
Regarding this proposal specifically, it's much easier to consider a new member for the warnings module than it is for builtins. :)
> 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
This seems to somewhat contradict (2) in the OP though, no?:
> 2. Looking it up is hard. If I Google "python ignore warnings" the top
result is a Stack Overflow question where neither the accepted answer
nor the most upvoted answer mention specifying a module. The second
Google result is the Python docs which are not easy to read through.
and potentially (3) as well. If one has already seen it or used it before, it's rather easy to navigate to "
docs.python.org" => enter warnings module => skim through member names (alternatively, just "import warnings; dir(warnings)" if you forgot what it was called or "help(warnings)" for a quick summary). From my perspective at least, if someone has to rely on a generic google search for "python ignore warnings" and didn't know to look for the warnings module, there's a good chance they have have minimal knowledge and experience of working with warning filters. A HOWTO guide that focuses on different useful things you can do with the warnings module could help with this, and would be written intentionally as something to be "read through" (as opposed to the warnings module docs, which is a bit more intended as a technical reference manual).
Also, as a sidenote, on my search engine for "python ignore warnings" I encountered
https://stackoverflow.com/questions/14463277/how-to-disable-python-warnings just below the results for the warning module documentation, where the most upvoted answer included usage of `warnings.simplefilter()`, `warnings.filterwarnings()`, and `warnings.catch_warnings()`. It didn't mention module-specific warning filters, but there is mention of it in the comments below the answer.
> 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.
While I agree in general, with filtering out warnings specifically there's a fine balance. At some point, it becomes tempting to just ignore the warnings instead of addressing the actual issue (particularly when a removal version isn't specified or is more than 2 major versions away). This of course doesn't apply so much though if the warning is being emitted from a 3rd party library rather than your own code. Besides submitting a bug report or patch and waiting, there's not much to do on the user end other than temporarily filtering it.
I think we already make it rather easy to do properly through `warnings.filterwarnings()` (as long as users are aware of it), so I think it's more of a concern of it being tedious when you have to explicitly specify each module to ignore a specific warning for. I'm in favor of making it easier to filter warnings the correct way rather than making it more tempting to put a massive blanket filter across all modules though.
It's certainly a valid concern and I'm very much open to considering a means to address it, I just don't think the proposed solution in this thread would be the right way to address it; at least not so far.