Add description for metadata argument of savefig #11755

timhoffm · 2018-07-23T17:54:23Z

PR Summary

anntzer · 2018-07-23T18:46:05Z

lib/matplotlib/backends/backend_agg.py

+
+        Parameters
+        ----------
+        filename_or_obj : str or PathLike of file-handle


anntzer · 2018-07-23T18:47:36Z

lib/matplotlib/backends/backend_agg.py

+        metadata : dict, optional
+            Metadata in the PNG file as key-value pairs of strings.
+            According to the PNG specification, keys must be shorter than 79
+            chars. The only supported encodingfor both keywords and values is


anntzer · 2018-07-23T18:48:49Z

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)


metadata={}

I've used None instead of {} because there are non-empty defaults depending on the backend.

anntzer · 2018-07-23T20:31:20Z

lib/matplotlib/backends/backend_agg.py

+            The file to write to.
+
+        metadata : dict, optional
+            Metadata in the PNG file as key-value pairs of strings.


Looking at the implementation of _png.cpp, looks like this should actually be "of latin-1-encodable strs or of bytes". The relevant chunk:

if (PyUnicode_Check(meta_key)) { PyObject *temp_key = PyUnicode_AsEncodedString(meta_key, "latin_1", "strict"); if (temp_key != NULL) { text[meta_pos].key = PyBytes_AsString(temp_key); } } else if (PyBytes_Check(meta_key)) { text[meta_pos].key = PyBytes_AsString(meta_key);

dstansby · 2018-07-24T17:11:58Z

lib/matplotlib/backends/backend_agg.py

+            According to the PNG specification, keys must be shorter than 79
+            chars.
+
+            The PNG specification defines some common keywords that may be


This is quite a long list, it might be worth linking to the relevant part of the PNG specification instead?

Thanks for the hint. I've added a link to the PNG specification. Nevertheless, I think it's good to have a list of the common keys here so that people don't have to check the external documentation just to get an idea how this is typically used.

dstansby · 2018-07-24T17:13:14Z

👍 , looks like it might need a rebase for circleci to work, and I think adding a link to the PNG specs would be good too.

timhoffm · 2018-07-24T22:55:08Z

Rebased.

dstansby · 2018-07-24T22:57:46Z

Anyone feel free to merge if/when CI passes.

anntzer · 2018-07-24T22:59:51Z

lib/matplotlib/backends/backend_agg.py

+            will be used.
+
+            For more details see the PNG specification:
+            https://www.w3.org/TR/2003/REC-PNG-20031110/#11keywords


Not a huge deal but I've grown fond of out-of-line rst links, e.g. here I'd have written before the list

`The PNG specification`_ defines some common keywords ...

and at the bottom

_The PNG specification: https://...

This way the plain text is just as readable and you get just a link in the HTML, which is normally what you want.

Does this work with line lengths? The link definition at the bottom would exceed 79 chars.

_The PNG specification: \ https://...

should also work (as long as the backslash stays an escape -- don't turn the docstring into a raw string!)

dstansby · 2018-07-26T16:36:44Z

Looks like the doc build is failing because of

Warning, treated as error:
/home/circleci/project/lib/matplotlib/backends/backend_agg.py:docstring of matplotlib.backends.backend_agg.FigureCanvasAgg.print_png:23:Unexpected indentation.

jklymak · 2018-07-27T21:30:23Z

lib/matplotlib/figure.py

+            - 'png' with Agg backend: See the parameter ``metadata`` of
+              `~.FigureCanvasAgg.print_png`.
+            - 'pdf' with pdf backend: See the parameter ``metadata`` of
+              `.PdfPages`.


This needs to specify between matplotlib.backends.backend_pdf.PdfPages and matplotlib.backends.backend_pgf.PdfPages I wasn't sure if you are OK w/ pushing to your PRs - if so next time I'll just push minor changes like this...

Not sure I understand the differences between pdf and pgf. You are welcome to push to my PRs.

Pgf needs tikz and a latex compiler to produce a PDF using the pgf file. I had no idea that it had a PdfPages method.

Ok. I've now linked to backend_pdf.PdfPages, which was my original intention.

timhoffm added the Documentation label Jul 23, 2018

anntzer reviewed Jul 23, 2018

View reviewed changes

lib/matplotlib/backends/backend_agg.py Outdated

Parameters

----------

filename_or_obj : str or PathLike of file-handle

Copy link

Contributor

anntzer Jul 23, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or

anntzer reviewed Jul 23, 2018

View reviewed changes

timhoffm force-pushed the doc-savefig-metadata branch 2 times, most recently from ddbb0f6 to 20fadd7 Compare July 23, 2018 20:24

anntzer reviewed Jul 23, 2018

View reviewed changes

timhoffm force-pushed the doc-savefig-metadata branch from 20fadd7 to 52c36af Compare July 23, 2018 21:17

dstansby reviewed Jul 24, 2018

View reviewed changes

timhoffm force-pushed the doc-savefig-metadata branch 2 times, most recently from 44d996d to 6768d6c Compare July 24, 2018 22:54

dstansby approved these changes Jul 24, 2018

View reviewed changes

dstansby added this to the v3.0 milestone Jul 24, 2018

anntzer reviewed Jul 24, 2018

View reviewed changes

jklymak added the status: needs revision label Jul 27, 2018

timhoffm force-pushed the doc-savefig-metadata branch from 6768d6c to 390a508 Compare July 27, 2018 20:58

jklymak reviewed Jul 27, 2018

View reviewed changes

timhoffm force-pushed the doc-savefig-metadata branch from 390a508 to 282c635 Compare July 27, 2018 21:49

Add description for metadata argument of savefig

d6c3885

timhoffm force-pushed the doc-savefig-metadata branch from 282c635 to d6c3885 Compare July 28, 2018 00:55

timhoffm removed the status: needs revision label Jul 28, 2018

jklymak merged commit e66de9c into matplotlib:master Jul 28, 2018

timhoffm deleted the doc-savefig-metadata branch July 28, 2018 13:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add description for metadata argument of savefig #11755

Add description for metadata argument of savefig #11755

timhoffm commented Jul 23, 2018

anntzer Jul 23, 2018

anntzer Jul 23, 2018

anntzer Jul 23, 2018

timhoffm Jul 23, 2018

anntzer Jul 23, 2018

dstansby Jul 24, 2018

timhoffm Jul 24, 2018

dstansby commented Jul 24, 2018

timhoffm commented Jul 24, 2018

dstansby commented Jul 24, 2018

anntzer Jul 24, 2018

timhoffm Jul 24, 2018

anntzer Jul 24, 2018

dstansby commented Jul 26, 2018

jklymak Jul 27, 2018

timhoffm Jul 28, 2018

jklymak Jul 28, 2018

timhoffm Jul 28, 2018 •

edited

Loading

Add description for metadata argument of savefig #11755

Add description for metadata argument of savefig #11755

Conversation

timhoffm commented Jul 23, 2018

PR Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dstansby commented Jul 24, 2018

timhoffm commented Jul 24, 2018

dstansby commented Jul 24, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dstansby commented Jul 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm Jul 28, 2018 • edited Loading

Choose a reason for hiding this comment

timhoffm Jul 28, 2018 •

edited

Loading