Improve docstring of imread() and imsave() #11318
Conversation
lib/matplotlib/image.py
Outdated
| supported via the optional dependency on `Pillow | ||
| <http://pillow.readthedocs.io/en/latest/>`_. Note, URL strings | ||
| may not be compatible with Pillow. Check the `Pillow documentation | ||
| <http://pillow.readthedocs.io/en/latest/>`_ for more information. |
There was a problem hiding this comment.
I would not repeat the link, or, if you really want to do so, use and external hyperlink target (http://docutils.sourceforge.net/docs/user/rst/quickref.html#external-hyperlink-targets). (In fact I would prefer always using external targets through the codebase as they make unrendered versions much more readable IMO, but that's a battle for another day.)
lib/matplotlib/image.py
Outdated
| fname : str or file-like | ||
| The image file to read. This can be a filename, a URL or a Python | ||
| file-like object. If using a file-like object, it must be opened in | ||
| binary |
There was a problem hiding this comment.
would also just write "binary-mode file-like".
lib/matplotlib/image.py
Outdated
| ----- | ||
| Matplotlib can only read PNGs natively. Further image formats are | ||
| supported via the optional dependency on Pillow. Note, URL strings | ||
| may not be compatible with Pillow. Check the `Pillow documentation`_ |
There was a problem hiding this comment.
"are not" (it is easy to check that it's not implemented by Pillow).
lib/matplotlib/image.py
Outdated
| ---------- | ||
| fname : str or file-like | ||
| The image file to read. This can be a filename, a URL or a Python | ||
| file-like object opened in read-binary mode". |
lib/matplotlib/image.py
Outdated
| *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`. |
There was a problem hiding this comment.
I find these "Defaults to :rc:blah.bloo" not as helpful as they should be because I don't have the default rcparams memorized. I think we should parenthetically add the default rcParam value in these cases...
| Path string to a filename, or a Python file-like object. | ||
| If *format* is *None* and *fname* is a string, the output | ||
| format is deduced from the extension of the filename. | ||
| The filename or a Python file-like object to store the image in. |
There was a problem hiding this comment.
I wouldn't kill the info that the filename's extension is used to determine the output format here. People rarely read the complete set of argument docs to find it in the format.
lib/matplotlib/image.py
Outdated
| Defaults to :rc:`image.cmap` ('viridis'). | ||
| format : str, optional | ||
| The file format. One of the file extensions supported by the active | ||
| backend. Most backends support png, pdf, ps, eps and svg. |
There was a problem hiding this comment.
"One of the file extensions supported by the active backend. Most backends support png, pdf, ps, eps and svg."
The first sentence is incorrect (and thus the second unnecessary): the backend will be automatically switched if needed. For example Agg only supports png but you can save pdfs with Agg active, as a temporary pdf canvas will be created on the fly. (And note that the implementation actually always uses an Agg canvas to start with :-))
If you really want to be pedantic the correct list would be "formats either supported by the active backend, or listed in FigureCanvasBase.filetypes", but in practice it's just whatever savefig supports and I wouldn't bother repeating the list here.
No description provided.