diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 1aa4930be825..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,53 +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. - 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. + Figure patch will also be transparent unless *facecolor* + and/or *edgecolor* are specified via kwargs. - 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. + 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). - pad_inches : float, default: :rc:`savefig.pad_inches` - Amount of padding around the figure when bbox_inches is 'tight'. + The transparency of these patches will be restored to their + original values upon exit of this function. + + 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'])