Merge pull request #13977 from anntzer/use-force-pyplot

tacaswell · web-flow · commit 40583b0722fb · 2019-05-06T15:37:48.000-04:00
API: Always import pyplot when calling matplotlib.use().
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1248,44 +1248,39 @@ def use(backend, warn=False, force=True):
         or a string of the form: ``module://my.module.name``.
 
     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.
+        If True and not *force*, emit a warning if a failure-to-switch
+        `ImportError` has been suppressed.
 
     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.
+        If True (the default), raise an `ImportError` if the backend cannot be
+        set up (either because it fails to import, or because an incompatible
+        GUI interactive framework is already running); if False, ignore the
+        failure.
 
     See Also
     --------
     :ref:`backends`
     matplotlib.get_backend
     """
     name = validate_backend(backend)
-
     if dict.__getitem__(rcParams, 'backend') == name:
         # Nothing to do if the requested backend is already set
         pass
-    elif 'matplotlib.pyplot' in sys.modules:
-        # pyplot has already been imported (which triggered backend selection)
-        # and the requested backend is different from the current one.
-        if force:
-            # if we are going to force switching the backend, pull in
-            # `switch_backend` from pyplot (which is already imported).
-            from matplotlib.pyplot import switch_backend
-            switch_backend(name)
-        elif warn:
-            # Only if we are not going to force the switch *and* warn is True,
-            # then direct users to `plt.switch_backend`.
-            cbook._warn_external(
-                "matplotlib.pyplot has already been imported, "
-                "this call will have no effect.")
     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.
+        # 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
+        try:
+            from matplotlib import pyplot as plt
+            plt.switch_backend(name)
+        except ImportError as exc:
+            if force:
+                raise
+            if warn:
+                cbook._warn_external(
+                    f"Failed to switch backend to {backend}: {exc}")
 
 
 if os.environ.get('MPLBACKEND'):
diff --git a/lib/matplotlib/tests/test_rcparams.py b/lib/matplotlib/tests/test_rcparams.py
@@ -1,6 +1,9 @@
 from collections import OrderedDict
 import copy
 import os
+from pathlib import Path
+import subprocess
+import sys
 from unittest import mock
 
 from cycler import cycler, Cycler
@@ -479,3 +482,28 @@ def test_if_rctemplate_would_be_valid(tmpdir):
                                 fail_on_error=True,
                                 use_default_template=False)
         assert len(record) == 0
+
+
+@pytest.mark.skipif(sys.platform != "linux", reason="Linux only")
+def test_backend_fallback_headless(tmpdir):
+    env = {**os.environ,
+           "DISPLAY": "", "MPLBACKEND": "", "MPLCONFIGDIR": str(tmpdir)}
+    with pytest.raises(subprocess.CalledProcessError):
+        subprocess.run(
+            [sys.executable, "-c",
+             "import matplotlib; matplotlib.use('tkagg')"],
+            env=env, check=True)
+
+
+@pytest.mark.skipif(sys.platform == "linux" and not os.environ.get("DISPLAY"),
+                    reason="headless")
+def test_backend_fallback_headful(tmpdir):
+    pytest.importorskip("tkinter")
+    env = {**os.environ, "MPLBACKEND": "", "MPLCONFIGDIR": str(tmpdir)}
+    backend = subprocess.check_output(
+        [sys.executable, "-c",
+         "import matplotlib.pyplot; print(matplotlib.get_backend())"],
+        env=env, universal_newlines=True)
+    # The actual backend will depend on what's installed, but at least tkagg is
+    # present.
+    assert backend.strip().lower() != "agg"
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -316,15 +316,22 @@ def my_plotter(ax, data1, data2, param_dict):
 # "interactive backends") and hardcopy backends to make image files
 # (PNG, SVG, PDF, PS; also referred to as "non-interactive backends").
 #
-# There are four ways to configure your backend. If they conflict each other,
+# There are three ways to configure your backend. If they conflict each other,
 # the method mentioned last in the following list will be used, e.g. calling
 # :func:`~matplotlib.use()` will override the setting in your ``matplotlibrc``.
 #
-#
-# #. The ``backend`` parameter in your ``matplotlibrc`` file (see
+# #. The :rc:`backend` parameter in your ``matplotlibrc`` file (see
 #    :doc:`/tutorials/introductory/customizing`)::
 #
-#        backend : WXAgg   # use wxpython with antigrain (agg) rendering
+#        backend : qt5agg   # use pyqt5 with antigrain (agg) rendering
+#
+#    If no backend is explicitly set in the ``matplotlibrc`` file, Matplotlib
+#    automatically detects a usable backend based on what is available on your
+#    system and on whether a GUI event loop is already running.
+#
+#    On Linux, if the environment variable :envvar:`DISPLAY` is unset, the
+#    "event loop" is identified as "headless", which causes a fallback to a
+#    noninteractive backend (agg).
 #
 # #. Setting the :envvar:`MPLBACKEND` environment variable, either for your
 #    current shell or for a single script.  On Unix::
@@ -351,12 +358,13 @@ def my_plotter(ax, data1, data2, param_dict):
 #       import matplotlib
 #       matplotlib.use('PS')   # generate postscript output by default
 #
-#    If you use the :func:`~matplotlib.use` function, this must be done before
-#    importing :mod:`matplotlib.pyplot`. Calling :func:`~matplotlib.use` after
-#    pyplot has been imported will have no effect.  Using
-#    :func:`~matplotlib.use` will require changes in your code if users want to
+#    If you use the `~matplotlib.use` function, this should be done before
+#    importing :mod:`matplotlib.pyplot`. Calling `~matplotlib.use` after pyplot
+#    has been imported may fail to switch the backend and raise an ImportError.
+#
+#    Using `~matplotlib.use` will require changes in your code if users want to
 #    use a different backend.  Therefore, you should avoid explicitly calling
-#    :func:`~matplotlib.use` unless absolutely necessary.
+#    `~matplotlib.use` unless absolutely necessary.
 #
 # .. note::
 #    Backend name specifications are not case-sensitive; e.g., 'GTK3Agg'
