Deprecate frameon kwarg and rcParam to savefig.

anntzer · anntzer · commit b69f8e6b99c8 · 2018-09-25T06:39:13.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/api/next_api_changes/2018-09-25-AL.rst b/doc/api/next_api_changes/2018-09-25-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/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -758,10 +758,10 @@ def gen_candidates():
 # listed in the rcParams (not included in _all_deprecated).
 # 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
@@ -1975,7 +1975,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.
 
@@ -2057,11 +2057,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
@@ -2087,8 +2082,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
@@ -533,7 +533,6 @@
                                 ## 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
