Description
I think the use of logging in matplotlib is not right.
Unfortunately the official logging documentation is not quite comprehensive. I'll try to explain in the following how I understand that logging should be used.
TLDR: I propose to just remove matplotlib._set_logger_verbose_level() and all logging issues are gone. - Maybe add a bit of documentation how to use logging, but that's really not matplotlib specific.
How logging should be used in simple cases
In the minimal case, libraries do only define a logger and call the respective info(), error() etc. functions on that logger.
_log = logging.getLogger(__name__)
In this case, the library does not care about handling at all. IMO this is generally good practice as the library will issue messages, but it will not care which will be delivered or where they will go to (stdout, file, ...). That's the task of the code using the library:
-
if the programmer does not care about logging at all, logging.lastResort is used, which is a StreamHandler to stderr. This makes sure the messages go somewhere even without configuration (note: this was introduced in 3.2).
-
if the programmer wants to control the logging, the simple way is logging.basicConfig(). This is sufficent to redirect output to files, set the global log level etc.
How matplotlib uses logging
Former times
There has been some argument parsing magic, so that passing --verbose to a script using matplotlib could be used to control matplotlib's logging. This has been removed because it's too magical and can badly interfere with the argument handling of a script.
Now
Currently, there is only matplotlib._set_logger_verbose_level().
If unused (default) the processes work as described above for loggging in simple cases.
The function binds a new StreamHandler (named console in the code) to _log and controls the level of the handler. This works ok for the case when the matplotlib-using programmer does not configure any logging himself: The messages are sent to console. logging.lastResort is not used. However, if logging basicConfig() is used, we have two handlers: console plus the one from the config, as can be seen when running
import matplotlib
import logging
logging.basicConfig()
matplotlib._set_logger_verbose_level('helpful')
matplotlib._log.info('test')
This outputs the message twice
test
INFO:matplotlib:test
luckily _set_logger_verbose_level() is private and should not be used currently.
Future
The proposal in #13129 is making _set_logger_verbose_level() indirectly public through some convenience functions. IMHO this is the wrong way to go as described above.
What we should do is just remove _set_logger_verbose_level(). It's standard use casescan be handled using logging.basicConfig(). e.g.
- redirecting to file: `logging.basicConfig(filename='errors.log')
- setting the level: `logging.basicConfig(level='debug')
logging.basicConfig() is actually more general, e.g.
- specifying the output format
- choosing between append and overwrite for a file.
- using another handler
- etc.
There's one special case that we do not cover: Logging matplotlibs output somewhere else that other logging output. That was possible / the case for _set_logger_verbose_level(). Not sure if it was by design or just accidentially. If a user really needs that, he has to attach a handler to the matplotlib logger (but also maybe set _log.propagate = False. We could add a convenience function for this, but IMHO this is rather an advance usage and it should be sufficient to make the matplotlib logger accessible.