Deprecate frameon kwarg and rcParam to savefig.

anntzer · anntzer · commit 57269b909bf2 · 2018-07-18T16:51:57.000+02:00
``frameon = False`` has *never* worked since its introduction in 2013
due to the buggy implementation that only took it into account if True:

    if frameon:
        original_frameon = self.get_frameon()
        self.set_frameon(frameon)

(despite the doc stating otherwise).  One can also set the facecolor
kwarg or savefig.facecolor rcParam to fully transparent for the same
effect.
diff --git a/doc/users/next_whats_new/2018-07-18-AL.rst b/doc/users/next_whats_new/2018-07-18-AL.rst
@@ -0,0 +1,7 @@
+Deprecations
+````````````
+
+The following API elements are deprecated:
+
+- the ``frameon`` kwarg to ``savefig`` and the ``savefig.frameon`` rcParam (use
+  ``facecolor`` instead),
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -15,12 +15,13 @@ revision, see the :ref:`github-stats`.
    For a release, add a new section after this, then comment out the include
    and toctree below by indenting them. Uncomment them after the release.
 
-  .. include:: next_whats_new/README.rst
-   .. toctree::
-      :glob:
-      :maxdepth: 1
+.. include:: next_whats_new/README.rst
 
-      next_whats_new/*
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   next_whats_new/*
 
 Ability to scale axis by a fixed order of magnitude
 ---------------------------------------------------
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -787,12 +787,12 @@ def gen_candidates():
 
 # rcParams deprecated; can use None to suppress warnings; remain actually
 # listed in the rcParams (not included in _all_deprecated).
-# Values are typles of (version,)
+# Values are tuples of (version,)
 _deprecated_remain_as_none = {
-    'axes.hold': ('2.1',),
     'backend.qt4': ('2.2',),
     'backend.qt5': ('2.2',),
     'text.latex.unicode': ('3.0',),
+    'savefig.frameon': ('3.1',),
 }
 
 
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1934,7 +1934,7 @@ def add_axobserver(self, func):
         """Whenever the axes state change, ``func(self)`` will be called."""
         self._axobservers.append(func)
 
-    def savefig(self, fname, *, frameon=None, transparent=None, **kwargs):
+    def savefig(self, fname, *, transparent=None, **kwargs):
         """
         Save the current figure.
 
@@ -2005,11 +2005,6 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs):
             transparency of these patches will be restored to their
             original values upon exit of this function.
 
-        frameon : bool
-            If *True*, the figure patch will be colored, if *False*, the
-            figure background will be transparent.  If not provided, the
-            rcParam 'savefig.frameon' will be used.
-
         bbox_inches : str or `~matplotlib.transforms.Bbox`, optional
             Bbox in inches. Only the given portion of the figure is
             saved. If 'tight', try to figure out the tight bbox of
@@ -2025,8 +2020,14 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs):
 
         """
         kwargs.setdefault('dpi', rcParams['savefig.dpi'])
-        if frameon is None:
-            frameon = rcParams['savefig.frameon']
+        if "frameon" in kwargs:
+            cbook.warn_deprecated("3.1", name="frameon", obj_type="kwarg",
+                                  alternative="facecolor")
+            frameon = kwargs.pop("frameon")
+            if frameon is None:
+                frameon = dict.__getitem__(rcParams, 'savefig.frameon')
+        else:
+            frameon = False  # Won't pass "if frameon:" below.
         if transparent is None:
             transparent = rcParams['savefig.transparent']
 
diff --git a/lib/matplotlib/mpl-data/stylelib/_classic_test.mplstyle b/lib/matplotlib/mpl-data/stylelib/_classic_test.mplstyle
@@ -418,7 +418,6 @@ savefig.pad_inches  : 0.1      # Padding to be used when bbox is set to 'tight'
 savefig.jpeg_quality: 95       # when a jpeg is saved, the default quality parameter.
 savefig.transparent : False    # setting that controls whether figures are saved with a
                                # transparent background by default
-savefig.frameon : True
 savefig.orientation : portrait
 
 # ps backend params
diff --git a/lib/matplotlib/mpl-data/stylelib/classic.mplstyle b/lib/matplotlib/mpl-data/stylelib/classic.mplstyle
@@ -422,7 +422,6 @@ savefig.pad_inches  : 0.1      # Padding to be used when bbox is set to 'tight'
 savefig.jpeg_quality: 95       # when a jpeg is saved, the default quality parameter.
 savefig.transparent : False    # setting that controls whether figures are saved with a
                                # transparent background by default
-savefig.frameon : True
 savefig.orientation : portrait
 
 # ps backend params
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -532,7 +532,6 @@ backend      : $TEMPLATE_BACKEND
                                 ## leave empty to always use current working directory
 #savefig.transparent : False    ## setting that controls whether figures are saved with a
                                 ## transparent background by default
-#savefig.frameon : True			## enable frame of figure when saving
 #savefig.orientation : portrait	## Orientation of saved figure
 
 ### tk backend params
