Add description for metadata argument of savefig

timhoffm · timhoffm · commit 6768d6c6a813 · 2018-07-24T22:18:44.000+02:00
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -485,6 +485,44 @@ def print_raw(self, filename_or_obj, *args, **kwargs):
     print_rgba = print_raw
 
     def print_png(self, filename_or_obj, *args, **kwargs):
+        """
+        Write the png data to the given file.
+
+        Parameters
+        ----------
+        filename_or_obj : str or PathLike or file-like object
+            The file to write to.
+
+        metadata : dict, optional
+            Metadata in the PNG file as key-value pairs of bytes or latin-1
+            encodable strings.
+            According to the PNG specification, keys must be shorter than 79
+            chars.
+
+            The PNG specification defines some common keywords that may be
+            used as appropriate:
+            - Title: Short (one line) title or caption for image.
+            - Author: Name of image's creator.
+            - Description: Description of image (possibly long).
+            - Copyright: Copyright notice.
+            - Creation Time: Time of original image creation
+              (usually RFC 1123 format).
+            - Software: Software used to create the image.
+            - Disclaimer: Legal disclaimer.
+            - Warning: Warning of nature of content.
+            - Source: Device used to create the image.
+            - Comment: Miscellaneous comment;
+              conversion from other image format.
+
+            Other keywords may be invented for other purposes.
+
+            If 'Software' is not given, an autogenerated value for matplotlib
+            will be used.
+
+            For more details see the PNG specification:
+            https://www.w3.org/TR/2003/REC-PNG-20031110/#11keywords
+
+        """
         FigureCanvasAgg.draw(self)
         renderer = self.get_renderer()
 
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1979,7 +1979,7 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs):
           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)
+                  frameon=None, metadata=None)
 
         The output formats available depend on the backend being used.
 
@@ -2059,6 +2059,16 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs):
             A list of extra artists that will be considered when the
             tight bbox is calculated.
 
+        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
+              `.PdfPages`.
+            - 'eps' and 'ps' with PS backend: Only 'Creator' is supported.
+
         """
         kwargs.setdefault('dpi', rcParams['savefig.dpi'])
         if frameon is None:
diff --git a/src/_png.cpp b/src/_png.cpp
@@ -128,6 +128,9 @@ const char *Py_write_png__doc__ =
     "    - Comment: Miscellaneous comment; conversion\n"
     "               from other image format\n"
     "\n"
+    "    For more details see the PNG specification:\n"
+    "    https://www.w3.org/TR/2003/REC-PNG-20031110/#11keywords\n"
+    "\n"
     "Returns\n"
     "-------\n"
     "buffer : bytes or None\n"
