Cleanup matplotlib.use

timhoffm · timhoffm · commit 511c3ae4e075 · 2019-01-10T18:43:13.000+01:00
diff --git a/doc/api/next_api_changes/2019-01-06-TH-use-param.rst b/doc/api/next_api_changes/2019-01-06-TH-use-param.rst
@@ -0,0 +1,7 @@
+API Changes
+```````````
+
+The first parameter of `matplotlib.use` has been renamed from *arg* to
+*backend*. This will only affect cases where that parameter has been set
+as a keyword argument. The common usage pattern as a positional argument
+``matplotlib.use('Qt5Agg')`` is not affected.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1297,15 +1297,15 @@ def __exit__(self, exc_type, exc_value, exc_tb):
         self.__fallback()
 
 
-def use(arg, warn=False, force=True):
+def use(backend, warn=False, force=True):
     """
-    Set the matplotlib backend to one of the known backends.
+    Select the matplotlib backend for rendering.
 
     Parameters
     ----------
-    arg : str
-        The backend to switch to.  This can either be one of the
-        'standard' backend names:
+    backend : str
+        The backend to switch to.  This can either be one of the standard
+        backend names, which are case-insensitive:
 
         - interactive backends:
           GTK3Agg, GTK3Cairo, MacOSX, nbAgg,
@@ -1317,52 +1317,47 @@ def use(arg, warn=False, force=True):
 
         or a string of the form: ``module://my.module.name``.
 
-        Note: Standard backend names are case-insensitive here.
+    warn : bool, optional, default: False
+        If True and not *force*, warn that the call will have no effect if
+        this is called after pyplot has been imported and a backend is set up.
 
-    warn : bool, optional
-        If True, warn if this is called after pyplot has been imported
-        and a backend is set up.
-
-        defaults to False.
-
-    force : bool, optional
+    force : bool, optional, default: True
         If True, attempt to switch the backend.   An ImportError is raised if
         an interactive backend is selected, but another interactive
-        backend has already started.  This defaults to True.
+        backend has already started.
 
     See Also
     --------
     :ref:`backends`
     matplotlib.get_backend
     """
-    name = validate_backend(arg)
+    name = validate_backend(backend)
 
-    # if setting back to the same thing, do nothing
-    if (dict.__getitem__(rcParams, 'backend') == name):
+    if dict.__getitem__(rcParams, 'backend') == name:
+        # Nothing to do if the requested backend is already set
         pass
-
-    # Check if we have already imported pyplot and triggered
-    # backend selection, do a bit more work
     elif 'matplotlib.pyplot' in sys.modules:
-        # If we are here then the requested is different than the current.
+        # pyplot has already been imported (which triggered backend selection)
+        # and the requested backend is different from the current one.
+
         # If we are going to force the switch, never warn, else, if warn
         # is True, then direct users to `plt.switch_backend`
         if (not force) and warn:
             cbook._warn_external(
-                ("matplotlib.pyplot as already been imported, "
-                 "this call will have no effect."))
+                "matplotlib.pyplot has already been imported, "
+                "this call will have no effect.")
 
         # if we are going to force switching the backend, pull in
         # `switch_backend` from pyplot.  This will only happen if
         # pyplot is already imported.
         if force:
             from matplotlib.pyplot import switch_backend
             switch_backend(name)
-    # Finally if pyplot is not imported update both rcParams and
-    # rcDefaults so restoring the defaults later with rcdefaults
-    # won't change the backend.  This is a bit of overkill as 'backend'
-    # is already in style.core.STYLE_BLACKLIST, but better to be safe.
     else:
+        # Finally if pyplot is not imported update both rcParams and
+        # rcDefaults so restoring the defaults later with rcdefaults
+        # won't change the backend.  This is a bit of overkill as 'backend'
+        # is already in style.core.STYLE_BLACKLIST, but better to be safe.
         rcParams['backend'] = rcParamsDefault['backend'] = name
 
 
