From a0ac7cf5ecb9e62b9f34d9d5aac05909986e7473 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 22 Jan 2019 12:21:47 +0100 Subject: [PATCH] Improve docs for format determination in savefig()/imsave(). Most importantly, the current backend is mostly irrelevant (unlike what the docs state), because we handle backend switching transparently. --- lib/matplotlib/figure.py | 22 +++++++++++----------- lib/matplotlib/image.py | 18 ++++++++---------- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 5c30805a7d73..963fee7c436f 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2009,17 +2009,17 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs): Parameters ---------- - fname : str or file-like object - A string containing a path to a filename, or a Python - file-like object, or possibly some backend-dependent object - such as :class:`~matplotlib.backends.backend_pdf.PdfPages`. + fname : str or PathLike or file-like object + A path, or a Python file-like object, or + possibly some backend-dependent object such as + `matplotlib.backends.backend_pdf.PdfPages`. - If *format* is *None* and *fname* is a string, the output - format is deduced from the extension of the filename. If - the filename has no extension, :rc:`savefig.format` is used. + If *format* is not set, then the output format is inferred from + the extension of *fname*, if any, and from :rc:`savefig.format` + otherwise. If *format* is set, it determines the output format. - If *fname* is not a string, remember to specify *format* to - ensure that the correct backend is used. + Hence, if *fname* is not a path or has no extension, remember to + specify *format* to ensure that the correct backend is used. Other Parameters ---------------- @@ -2063,8 +2063,8 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs): output. format : str - One of the file extensions supported by the active - backend. Most backends support png, pdf, ps, eps and svg. + 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 diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py index 2924b74899cc..a3fd6a304468 100644 --- a/lib/matplotlib/image.py +++ b/lib/matplotlib/image.py @@ -1398,16 +1398,15 @@ def imread(fname, format=None): def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None, origin=None, dpi=100): """ - Save an array as in image file. - - The output formats available depend on the backend being used. + Save an array as an image file. Parameters ---------- - fname : str or file-like - The filename or a Python file-like object to store the image in. - The necessary output format is inferred from the filename extension - but may be explicitly overwritten using *format*. + fname : str or PathLike file-like + A path or a Python file-like object to store the image in. + If *format* is not set, then the output format is inferred from the + extension of *fname*, if any, and from :rc:`savefig.format` otherwise. + If *format* is set, it determines the output format. arr : array-like The image data. The shape can be one of MxN (luminance), MxNx3 (RGB) or MxNx4 (RGBA). @@ -1421,9 +1420,8 @@ def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None, maps scalar data to colors. It is ignored for RGB(A) data. Defaults to :rc:`image.cmap` ('viridis'). format : str, optional - The file format, e.g. 'png', 'pdf', 'svg', ... . If not given, the - format is deduced form the filename extension in *fname*. - See `.Figure.savefig` for details. + The file format, e.g. 'png', 'pdf', 'svg', ... The behavior when this + is unset is documented under *fname*. origin : {'upper', 'lower'}, optional Indicates whether the ``(0, 0)`` index of the array is in the upper left or lower left corner of the axes. Defaults to :rc:`image.origin`