ENH: add a user-freindly verbose interface

jklymak · jklymak · commit e575fc7f9342 · 2019-01-22T07:57:15.000-08:00
ENH: set level to INFO and add pyplot.debug()
DOC: add whats new and update FAQs
DOC: fix wording
ENH: change name to set_loglevel
FIX: lower case
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -448,6 +448,11 @@ Then they will receive messages like::
   matplotlib.yourmodulename: 347 - INFO - Here is some information
   matplotlib.yourmodulename: 348 - DEBUG - Here is some more detailed information
 
+More straight forward helper methods are available to end-users as well::
+
+  import matplotlib.pyplot as plt
+  plt.set_loglevel(level='info')  # or plt.set_loglevel(level='debug')
+
 Which logging level to use?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/faq/troubleshooting_faq.rst b/doc/faq/troubleshooting_faq.rst
@@ -120,10 +120,16 @@ provide the following information in your e-mail to the `mailing list
 
      python -c "from logging import *; basicConfig(level=DEBUG); from pylab import *; plot(); show()"
 
+  If you want to trigger logging in a script, it can be done with helper
+  functions::
 
-  If you want to put the debugging hooks in your own code, then the
-  most simple way to do so is to insert the following *before* any calls
-  to ``import matplotlib``::
+    import matplotlib.pyplot as plt
+    plt.set_loglevel(level='info')  # or plt.set_loglevel(level='debug')
+
+
+  If you want to put full debugging hooks in your own code, including
+  debug information when matplotlib starts up, then the way to do so is to
+  insert the following *before* any calls to ``import matplotlib``::
 
     import logging
     logging.basicConfig(level=logging.DEBUG)
diff --git a/doc/users/next_whats_new/pyplot_verbose.rst b/doc/users/next_whats_new/pyplot_verbose.rst
@@ -0,0 +1,7 @@
+:orphan:
+
+New methods for verbose logging
+-------------------------------
+
+If more debugging information is required, the user can call
+the `.pyplot.set_loglevel` method.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -207,14 +207,35 @@ def _check_versions():
     sys.argv = ['modpython']
 
 
-_verbose_msg = """\
-matplotlib.verbose is deprecated;
-Command line argument --verbose-LEVEL is deprecated.
-This functionality is now provided by the standard
-python logging library.  To get more (or less) logging output:
-    import logging
-    logger = logging.getLogger('matplotlib')
-    logger.set_level(logging.INFO)"""
+def set_loglevel(level='info'):
+    """
+    Shortcut to set the logging level of the logging module.
+
+    Parameters
+    ----------
+    level : str or bool
+        If True set logging level to "INFO" for matplotlib module.
+        If FALSE set logging level to "WARNING" for matplotlib module (this
+        is the default level if ``set_loglevel`` is not called). If a string,
+        must be one of ['warning', 'info', 'debug'], in order of increasing
+        verbosity.
+
+    Notes
+    -----
+    This is the same as the standard python `logging` module::
+
+        import logging
+
+        _log = logging.getLogger(__name__)
+        _log.setLevel(logging.INFO)  # or logging.WARNING, logging.INFO
+
+    """
+
+    if level is True:
+        level = 'info'
+    if level is False:
+        level = 'warning'
+    _set_logger_verbose_level(level_str=level.lower())
 
 
 def _set_logger_verbose_level(level_str='silent', file_str='sys.stdout'):
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1997,6 +1997,32 @@ def colormaps():
     return sorted(cm.cmap_d)
 
 
+def set_loglevel(level='info'):
+    """
+    Shortcut to set the debugging level of the logging module.
+
+    Parameters
+    ----------
+    level : str or bool (optional)
+        If *True* (default) set logging level to "INFO" for matplotlib module.
+        If *False* set logging level to "WARNING" for matplotlib module (this
+        is the default level if ``verbose`` is not called). If a string, must
+        be one of ['warning', 'info', 'debug'], in order of increasing
+        verbosity.
+
+    Notes
+    -----
+    This is the same as the standard python `logging` module::
+
+        import logging
+
+        _log = logging.getLogger(__name__)
+        _log.setLevel(logging.DEBUG)  # or logging.WARNING, logging.INFO
+
+    """
+    matplotlib.set_loglevel(level=level)
+
+
 def _setup_pyplot_info_docstrings():
     """
     Generates the plotting docstring.
