Deprecate the 'warn' parameter to matplotlib.use().

anntzer · anntzer · commit 7902910e16a7 · 2019-05-22T14:47:58.000+02:00
Right now, the only case where the 'warn' parameter to use() has an
observable effect is if the user calls
`use(some_backend, warn=True, force=False)` (the default is
`warn=False, force=True`) and `some_backend` cannot be switched to.

If they really want a warning in that case and not an exception (why?),
they can just do
```
try: use(some_backend)
except ImportError: warnings.warn(...)
```
instead.

Given the non-obvious interaction between `warn` and `force`, just
deprecate `warn`.

We could even deprecate `force` and tell user to catch ImportErrors if
they know a switch can fail and that they want to silently ignore the
switch failure, but I guess someone will complain that
`use(some_backend, force=False)` is so much shorter to write than
```
try: use(some_backend)
except ImportError: pass
```
...
diff --git a/doc/api/next_api_changes/2019-05-06-AL.rst b/doc/api/next_api_changes/2019-05-06-AL.rst
@@ -0,0 +1,6 @@
+Deprecations
+````````````
+
+The ``warn`` parameter to `matplotlib.use()` is deprecated (catch the
+`ImportError` emitted on backend switch failure and reemit a warning yourself
+if so desired).
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1226,6 +1226,7 @@ def __exit__(self, exc_type, exc_value, exc_tb):
 
 
 @cbook._rename_parameter("3.1", "arg", "backend")
+@cbook._delete_parameter("3.1", "warn")
 def use(backend, warn=False, force=True):
     """
     Select the backend used for rendering and GUI integration.
@@ -1248,7 +1249,7 @@ def use(backend, warn=False, force=True):
 
     warn : bool, optional, default: False
         If True and not *force*, emit a warning if a failure-to-switch
-        `ImportError` has been suppressed.
+        `ImportError` has been suppressed.  This parameter is deprecated.
 
     force : bool, optional, default: True
         If True (the default), raise an `ImportError` if the backend cannot be
diff --git a/lib/matplotlib/testing/__init__.py b/lib/matplotlib/testing/__init__.py
@@ -50,7 +50,7 @@ def setup():
                 "Could not set locale to English/United States. "
                 "Some date-related tests may fail.")
 
-    mpl.use('Agg', force=True, warn=False)  # use Agg backend for these tests
+    mpl.use('Agg')
 
     with cbook._suppress_matplotlib_deprecation_warning():
         mpl.rcdefaults()  # Start with all defaults
