diff --git a/doc/users/next_whats_new/loggers.rst b/doc/users/next_whats_new/loggers.rst new file mode 100644 index 000000000000..0c64998c6e3d --- /dev/null +++ b/doc/users/next_whats_new/loggers.rst @@ -0,0 +1,10 @@ +``set_loglevel`` can opt-out of manipulating logging handlers +------------------------------------------------------------- + +It is now possible to configure the logging level of the Matplotilb standard +library logger without also implicitly installing a handler via both +`matplotlib.set_loglevel` and `matplotlib.pyplot.set_loglevel` :: + + mpl.set_loglevel('debug', ensure_handler=False) + # or + plt.set_loglevel('debug', ensure_handler=False) diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 50033b212a93..3b4f9aa76876 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -230,27 +230,43 @@ def _ensure_handler(): return handler -def set_loglevel(level): +def set_loglevel(level, *, ensure_handler=True): """ - Set Matplotlib's root logger and root logger handler level, creating - the handler if it does not exist yet. + Configure Matplotlib's logging levels. + + Matplotlib uses the standard library `logging` framework under the root + logger 'matplotlib'. This is a helper function to: + + - set Matplotlib's root logger level + - optionally set the root logger handler's level, creating the handler + if it does not exist yet Typically, one should call ``set_loglevel("info")`` or ``set_loglevel("debug")`` to get additional debugging information. + Users or applications that are installing their own logging handlers + may want to directly manipulate ``logging.getLogger('matplotlib')`` rather + than use this function. + Parameters ---------- level : {"notset", "debug", "info", "warning", "error", "critical"} The log level of the handler. + ensure_handler : bool + If True will ensure that there is a `logging.StreamHandler` added to + the matplotlib root logger and that its level matches the logger level. + Notes ----- The first time this function is called, an additional handler is attached to Matplotlib's root handler; this handler is reused every time and this function simply manipulates the logger and handler's level. + """ _log.setLevel(level.upper()) - _ensure_handler().setLevel(level.upper()) + if ensure_handler: + _ensure_handler().setLevel(level.upper()) def _logged_cached(fmt, func=None):