From 6c2d146a2b63fa1ee4bd231a4c7e5700e613bf11 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 13 May 2021 19:06:24 -0400 Subject: [PATCH 1/2] DOC: clarify that savefig(..., transparent=False) has no effect re-closes #14339 --- lib/matplotlib/figure.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 1aa4930be825..a3dfcb791226 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2890,8 +2890,12 @@ def savefig(self, fname, *, transparent=None, **kwargs): transparent : bool If *True*, the Axes patches will all be transparent; the - figure patch will also be transparent unless facecolor + Figure patch will also be transparent unless facecolor and/or edgecolor are specified via kwargs. + + If *False* has no effect and leaves the color of the Axes and + Figure patches as they are. + 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 From d0439771eadbfb03c9b28a5e245f45586a49db28 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 13 May 2021 22:04:36 -0400 Subject: [PATCH 2/2] DOC: update Figure.savefig signature and re-order docstring --- lib/matplotlib/figure.py | 87 +++++++++++++++++++++------------------- 1 file changed, 46 insertions(+), 41 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index a3dfcb791226..db2d99e08fc9 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2837,10 +2837,11 @@ def savefig(self, fname, *, transparent=None, **kwargs): Call signature:: - savefig(fname, dpi=None, facecolor='w', edgecolor='w', - orientation='portrait', papertype=None, format=None, - transparent=False, bbox_inches=None, pad_inches=0.1, - frameon=None, metadata=None) + savefig(fname, *, dpi='figure', format=None, metadata=None, + bbox_inches=None, pad_inches=0.1, + facecolor='auto', edgecolor='auto', + backend=None, **kwargs + ) The available output formats depend on the backend being used. @@ -2868,6 +2869,29 @@ def savefig(self, fname, *, transparent=None, **kwargs): The resolution in dots per inch. If 'figure', use the figure's dpi value. + format : str + The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when + this is unset is documented under *fname*. + + metadata : dict, optional + Key/value pairs to store in the image metadata. The supported keys + and defaults depend on the image format and backend: + + - 'png' with Agg backend: See the parameter ``metadata`` of + `~.FigureCanvasAgg.print_png`. + - 'pdf' with pdf backend: See the parameter ``metadata`` of + `~.backend_pdf.PdfPages`. + - 'svg' with svg backend: See the parameter ``metadata`` of + `~.FigureCanvasSVG.print_svg`. + - 'eps' and 'ps' with PS backend: Only 'Creator' is supported. + + bbox_inches : str or `.Bbox`, default: :rc:`savefig.bbox` + Bounding box in inches: only the given portion of the figure is + saved. If 'tight', try to figure out the tight bbox of the figure. + + pad_inches : float, default: :rc:`savefig.pad_inches` + Amount of padding around the figure when bbox_inches is 'tight'. + facecolor : color or 'auto', default: :rc:`savefig.facecolor` The facecolor of the figure. If 'auto', use the current figure facecolor. @@ -2876,6 +2900,14 @@ def savefig(self, fname, *, transparent=None, **kwargs): The edgecolor of the figure. If 'auto', use the current figure edgecolor. + backend : str, optional + Use a non-default backend to render the file, e.g. to render a + png file with the "cairo" backend rather than the default "agg", + or a pdf file with the "pgf" backend rather than the default + "pdf". Note that the default backend is normally sufficient. See + :ref:`the-builtin-backends` for a list of valid backends for each + file format. Custom backends can be referenced as "module://...". + orientation : {'landscape', 'portrait'} Currently only supported by the postscript backend. @@ -2884,57 +2916,30 @@ def savefig(self, fname, *, transparent=None, **kwargs): 'a10', 'b0' through 'b10'. Only supported for postscript output. - format : str - The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when - this is unset is documented under *fname*. - 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. + Figure patch will also be transparent unless *facecolor* + and/or *edgecolor* are specified via kwargs. - If *False* has no effect and leaves the color of the Axes and - Figure patches as they are. + If *False* has no effect and the color of the Axes and + Figure patches are unchanged (unless the Figure patch + is specified via the *facecolor* and/or *edgecolor* keyword + arguments in which case those colors are used). - 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 + The transparency of these patches will be restored to their original values upon exit of this function. - bbox_inches : str or `.Bbox`, default: :rc:`savefig.bbox` - Bounding box in inches: only the given portion of the figure is - saved. If 'tight', try to figure out the tight bbox of the figure. - - pad_inches : float, default: :rc:`savefig.pad_inches` - Amount of padding around the figure when bbox_inches is 'tight'. + This is useful, for example, for displaying + a plot on top of a colored background on a web page. bbox_extra_artists : list of `~matplotlib.artist.Artist`, optional A list of extra artists that will be considered when the tight bbox is calculated. - backend : str, optional - Use a non-default backend to render the file, e.g. to render a - png file with the "cairo" backend rather than the default "agg", - or a pdf file with the "pgf" backend rather than the default - "pdf". Note that the default backend is normally sufficient. See - :ref:`the-builtin-backends` for a list of valid backends for each - file format. Custom backends can be referenced as "module://...". - - metadata : dict, optional - Key/value pairs to store in the image metadata. The supported keys - and defaults depend on the image format and backend: - - - 'png' with Agg backend: See the parameter ``metadata`` of - `~.FigureCanvasAgg.print_png`. - - 'pdf' with pdf backend: See the parameter ``metadata`` of - `~.backend_pdf.PdfPages`. - - 'svg' with svg backend: See the parameter ``metadata`` of - `~.FigureCanvasSVG.print_svg`. - - 'eps' and 'ps' with PS backend: Only 'Creator' is supported. - pil_kwargs : dict, optional Additional keyword arguments that are passed to `PIL.Image.Image.save` when saving the figure. + """ kwargs.setdefault('dpi', mpl.rcParams['savefig.dpi'])