Deprecate savefig.facecolor, savefig.edgecolor, and savefig.transparent.

anntzer · anntzer · commit f2bb69084a20 · 2017-12-16T01:16:30.000-08:00
They cause a number of complications for print_figure (which needs to
temporarily switch the figure and axes face and edge colors) that are
unnecessary (the user can directly set the color they wish (including
transparent) on the figure patch instead; an rcParam is even available
for that purpose).
diff --git a/doc/api/api_changes/2017-12-16-AL.rst b/doc/api/api_changes/2017-12-16-AL.rst
@@ -0,0 +1,12 @@
+Deprecation of savefig-time modification of the figure patch face and edge colors
+`````````````````````````````````````````````````````````````````````````````````
+
+The ``facecolor``, ``edgecolor``, and ``transparent`` keyword arguments to
+`~.Figure.savefig` and `~.FigureCanvasBase.print_figure`, and the associated
+``savefig.facecolor``, ``savefig.edgecolor``, and ``savefig.transparent``
+rcParams, have been deprecated.  As a replacement for the first two
+options, directly set the facecolor and edgecolor of the figure patch
+(``figure.patch``), or set the ``figure.facecolor`` and ``figure.edgecolor``
+rcParams.  As a replacement for ``transparent``, set both the figure
+patch color and the axes patch color to transparent, or likewise set the
+corresponding rcParams.
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -862,7 +862,13 @@ def gen_candidates():
 _obsolete_set = {'text.dvipnghack', 'legend.isaxes'}
 
 # The following may use a value of None to suppress the warning.
-_deprecated_set = {'axes.hold'}  # do NOT include in _all_deprecated
+# Do NOT include in _all_deprecated.
+_deprecated_set = {
+    'axes.hold',
+    'savefig.facecolor',
+    'savefig.edgecolor',
+    'savefig.transparent',
+}
 
 _all_deprecated = set(itertools.chain(
     _deprecated_ignore_map, _deprecated_map, _obsolete_set))
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2132,12 +2132,6 @@ def print_figure(self, filename, dpi=None, facecolor=None, edgecolor=None,
         dpi : scalar, optional
             the dots per inch to save the figure in; if None, use savefig.dpi
 
-        facecolor : color spec or None, optional
-            the facecolor of the figure; if None, defaults to savefig.facecolor
-
-        edgecolor : color spec or None, optional
-            the edgecolor of the figure; if None, defaults to savefig.edgecolor
-
         format : str, optional
             when set, forcibly set the file format to save to
 
@@ -2179,8 +2173,18 @@ def print_figure(self, filename, dpi=None, facecolor=None, edgecolor=None,
 
         if facecolor is None:
             facecolor = rcParams['savefig.facecolor']
+        else:
+            cbook.warn_deprecated(
+                "2.2",
+                "The 'facecolor' kwarg is deprecated; set the figure's "
+                "facecolor ('figure.patch.facecolor') instead")
         if edgecolor is None:
             edgecolor = rcParams['savefig.edgecolor']
+        else:
+            cbook.warn_deprecated(
+                "2.2",
+                "The 'edgecolor' kwarg is deprecated; set the figure's "
+                "edgecolor ('figure.patch.edgecolor') instead")
 
         origDPI = self.figure.dpi
         origfacecolor = self.figure.get_facecolor()
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -569,12 +569,9 @@ def print_jpg(self, filename_or_obj, *args, **kwargs):
             buf, size = self.print_to_buffer()
             if kwargs.pop("dryrun", False):
                 return
-            # The image is "pasted" onto a white background image to safely
-            # handle any transparency
+            # Paste image onto a white background to handle transparency.
             image = Image.frombuffer('RGBA', size, buf, 'raw', 'RGBA', 0, 1)
-            rgba = mcolors.to_rgba(rcParams['savefig.facecolor'])
-            color = tuple([int(x * 255.0) for x in rgba[:3]])
-            background = Image.new('RGB', size, color)
+            background = Image.new('RGB', size, (255, 255, 255))
             background.paste(image, image)
             options = {k: kwargs[k]
                        for k in ['quality', 'optimize', 'progressive', 'dpi']
diff --git a/lib/matplotlib/backends/web_backend/nbagg_uat.ipynb b/lib/matplotlib/backends/web_backend/nbagg_uat.ipynb
@@ -411,8 +411,6 @@
    "outputs": [],
    "source": [
     "import matplotlib\n",
-    "matplotlib.rcParams.update({'figure.facecolor': 'red',\n",
-    "                            'savefig.facecolor': 'yellow'})\n",
     "plt.figure()\n",
     "plt.plot([3, 2, 1])\n",
     "\n",
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1792,12 +1792,6 @@ def savefig(self, fname, **kwargs):
             the value ``savefig.dpi`` in the matplotlibrc file. If 'figure'
             it will set the dpi to be the value of the figure.
 
-        facecolor : color spec or None, optional
-            the facecolor of the figure; if None, defaults to savefig.facecolor
-
-        edgecolor : color spec or None, optional
-            the edgecolor of the figure; if None, defaults to savefig.edgecolor
-
         orientation : {'landscape', 'portrait'}
             not supported on all backends; currently only on postscript output
 
@@ -1810,15 +1804,6 @@ def savefig(self, fname, **kwargs):
             One of the file extensions supported by the active
             backend.  Most backends support png, pdf, ps, eps and svg.
 
-        transparent : bool
-            If *True*, the axes patches will all be transparent; the
-            figure patch will also be transparent unless facecolor
-            and/or edgecolor are specified via kwargs.
-            This is useful, for example, for displaying
-            a plot on top of a colored background on a web page.  The
-            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
@@ -1840,6 +1825,24 @@ def savefig(self, fname, **kwargs):
         """
         kwargs.setdefault('dpi', rcParams['savefig.dpi'])
         frameon = kwargs.pop('frameon', rcParams['savefig.frameon'])
+
+        if "transparent" in kwargs:
+            cbook.warn_deprecated(
+                "2.2",
+                "The 'transparent' kwarg is deprecated; set the figure's and "
+                "axes' facecolor ('figure.patch.facecolor', 'axes.patch."
+                "facecolor') to fully transparent ('none') instead")
+        if "facecolor" in kwargs:
+            cbook.warn_deprecated(
+                "2.2",
+                "The 'facecolor' kwarg is deprecated; set the figure's "
+                "facecolor ('figure.patch.facecolor') instead")
+        if "edgecolor" in kwargs:
+            cbook.warn_deprecated(
+                "2.2",
+                "The 'edgecolor' kwarg is deprecated; set the figure's "
+                "edgecolor ('figure.patch.edgecolor') instead")
+
         transparent = kwargs.pop('transparent',
                                  rcParams['savefig.transparent'])
 
diff --git a/lib/matplotlib/mpl-data/stylelib/_classic_test.mplstyle b/lib/matplotlib/mpl-data/stylelib/_classic_test.mplstyle
@@ -290,9 +290,6 @@ legend.shadow        : False
 legend.frameon       : True   # whether or not to draw a frame around legend
 legend.framealpha    : None    # opacity of legend frame
 legend.scatterpoints : 3 # number of scatter points
-legend.facecolor     : inherit   # legend background color (when 'inherit' uses axes.facecolor)
-legend.edgecolor     : inherit   # legend edge color (when 'inherit' uses axes.edgecolor)
-
 
 
 ### FIGURE
@@ -418,8 +415,6 @@ savefig.bbox        : standard # 'tight' or 'standard'.
                                # use ffmpeg_file instead
 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
 
diff --git a/lib/matplotlib/mpl-data/stylelib/classic.mplstyle b/lib/matplotlib/mpl-data/stylelib/classic.mplstyle
@@ -410,8 +410,6 @@ path.sketch : None # May be none, or a 3-tuple of the form (scale, length,
 # e.g., you may want a higher resolution, or to make the figure
 # background white
 savefig.dpi         : 100      # figure dots per inch
-savefig.facecolor   : w        # figure facecolor when saving
-savefig.edgecolor   : w        # figure edgecolor when saving
 savefig.format      : png      # png, ps, pdf, svg
 savefig.bbox        : standard # 'tight' or 'standard'.
                                # 'tight' is incompatible with pipe-based animation
@@ -420,8 +418,6 @@ savefig.bbox        : standard # 'tight' or 'standard'.
                                # use ffmpeg_file instead
 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
 
diff --git a/lib/matplotlib/mpl-data/stylelib/dark_background.mplstyle b/lib/matplotlib/mpl-data/stylelib/dark_background.mplstyle
@@ -17,7 +17,3 @@ grid.color: white
 
 figure.facecolor: black
 figure.edgecolor: black
-
-savefig.facecolor: black
-savefig.edgecolor: black
-
diff --git a/lib/matplotlib/mpl-data/stylelib/fivethirtyeight.mplstyle b/lib/matplotlib/mpl-data/stylelib/fivethirtyeight.mplstyle
@@ -31,9 +31,6 @@ ytick.minor.size: 0
 
 font.size:14.0
 
-savefig.edgecolor: f0f0f0
-savefig.facecolor: f0f0f0
-
 figure.subplot.left: 0.08
 figure.subplot.right: 0.95
 figure.subplot.bottom: 0.07
diff --git a/lib/matplotlib/mpl-data/stylelib/grayscale.mplstyle b/lib/matplotlib/mpl-data/stylelib/grayscale.mplstyle
@@ -23,7 +23,3 @@ figure.facecolor: 0.75
 figure.edgecolor: white
 
 image.cmap: gray
-
-savefig.facecolor: white
-savefig.edgecolor: white
-
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -511,8 +511,6 @@ backend      : $TEMPLATE_BACKEND
 # e.g., you may want a higher resolution, or to make the figure
 # background white
 #savefig.dpi         : figure   # figure dots per inch or 'figure'
-#savefig.facecolor   : white    # figure facecolor when saving
-#savefig.edgecolor   : white    # figure edgecolor when saving
 #savefig.format      : png      # png, ps, pdf, svg
 #savefig.bbox        : standard # 'tight' or 'standard'.
                                 # 'tight' is incompatible with pipe-based animation
@@ -523,8 +521,6 @@ backend      : $TEMPLATE_BACKEND
 #savefig.jpeg_quality: 95       # when a jpeg is saved, the default quality parameter.
 #savefig.directory   : ~        # default directory in savefig dialog box,
                                 # leave empty to always use current working directory
-#savefig.transparent : False    # setting that controls whether figures are saved with a
-                                # transparent background by default
 
 # tk backend params
 #tk.window_focus   : False    # Maintain shell focus for TkAgg
diff --git a/tutorials/intermediate/tight_layout_guide.py b/tutorials/intermediate/tight_layout_guide.py
@@ -24,7 +24,7 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
-plt.rcParams['savefig.facecolor'] = "0.8"
+plt.rcParams['figure.facecolor'] = "0.8"
 
 
 def example_plot(ax, fontsize=12):
