MNT: Prefer capitalized logging levels (matplotlib#30339)

* MNT: Prefer capitalized logging levels

matplotlib#30302 just introduced literals for the log levels. Previously, the
situation was a bit vague: While the docstring described the levels
as all lowercase, in fact any casing is accepted. This PR changes the
preferred casing to be all-capitalized in analogy to the logging
standard library, which only supports this casing. Lowercase remains
supported because it's not worth an API breakage.

We might later consider to also accept logging levels directly, i.e.
`logging.DEBUG` to be more congruent with the logging library. But this
can be done any time. It's important to get this PR in soon to not
release the typing Literal in lowercase form.

* Update lib/matplotlib/__init__.py

Co-authored-by: Thomas A Caswell <[email protected]>

---------

Co-authored-by: Thomas A Caswell <[email protected]>

Author: timhoffm

doc/devel/coding_guide.rst

@@ -215,7 +215,7 @@ If an end-user of Matplotlib sets up `logging` to display at levels more
 verbose than ``logging.WARNING`` in their code with the Matplotlib-provided
 helper::
 
-  plt.set_loglevel("debug")
+  plt.set_loglevel("DEBUG")
 
 or manually with ::
 

doc/devel/troubleshooting.rst

@@ -23,7 +23,7 @@ mode::
     git clean -xfd
     git pull
     python -m pip install -v . > build.out
-    python -c "from pylab import *; set_loglevel('debug'); plot(); show()" > run.out
+    python -c "from pylab import *; set_loglevel('DEBUG'); plot(); show()" > run.out
 
 and post :file:`build.out` and :file:`run.out` to the `matplotlib-devel
 <https://mail.python.org/mailman/listinfo/matplotlib-devel>`_

doc/install/index.rst

@@ -179,7 +179,7 @@ development environment such as :program:`IDLE` which add additional
 complexities. Open up a UNIX shell or a DOS command prompt and run, for
 example::
 
-   python -c "from pylab import *; set_loglevel('debug'); plot(); show()"
+   python -c "from pylab import *; set_loglevel('DEBUG'); plot(); show()"
 
 This will give you additional information about which backends Matplotlib is
 loading, version information, and more. At this point you might want to make

doc/users/faq.rst

@@ -367,7 +367,7 @@ provide the following information in your e-mail to the `mailing list
 * Matplotlib provides debugging information through the `logging` library, and
   a helper function to set the logging level: one can call ::
 
-    plt.set_loglevel("info")  # or "debug" for more info
+    plt.set_loglevel("INFO")  # or "DEBUG" for more info
 
   to obtain this debugging information.
 

lib/matplotlib/__init__.py

@@ -292,17 +292,21 @@ def set_loglevel(level):
     - 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.
+    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.
+    level : {"NOTSET", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+        The log level as defined in `Python logging levels
+        <https://docs.python.org/3/library/logging.html#logging-levels>`__.
+
+        For backwards compatibility, the levels are case-insensitive, but
+        the capitalized version is preferred in analogy to `logging.Logger.setLevel`.
 
     Notes
     -----

lib/matplotlib/typing.py

@@ -93,7 +93,7 @@
 CapStyleType: TypeAlias = CapStyle | Literal["butt", "projecting", "round"]
 """Line cap styles. See :doc:`/gallery/lines_bars_and_markers/capstyle`."""
 
-LogLevel: TypeAlias = Literal["notset", "debug", "info", "warning", "error", "critical"]
+LogLevel: TypeAlias = Literal["NOTSET", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 """Literal type for valid logging levels accepted by `set_loglevel()`."""
 
 CoordsBaseType = Union[