Improve docs for format determination in savefig()/imsave().

anntzer · anntzer · commit a0ac7cf5ecb9 · 2019-01-22T12:23:47.000+01:00
Most importantly, the current backend is mostly irrelevant (unlike what
the docs state), because we handle backend switching transparently.
diff --git 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
@@ -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`
