Add a backend kwarg to savefig. #15536

anntzer · 2019-10-27T13:20:02Z

This makes it easier e.g. to test the pgf backend without globally
switching the backend.

Makes it easier to work on pgf related issues; also helps with #13994 (attn @ArchangeGabriel; see changelog).

PR Summary

PR Checklist

Has Pytest style unit tests
Code is Flake 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

lib/matplotlib/backend_bases.py

tacaswell · 2019-10-27T20:13:26Z

Notionally 👍 one slight behavior question.

Adding a the new parameter which is sometimes None first is a bit odd to me, but I see the argument for that as it is consulted first.

anntzer · 2019-10-27T20:41:10Z

backend has priority over fmt, so that's why I put them in this order (also, it's private API anyways).

timhoffm · 2019-10-27T20:51:58Z

I'm a bit hesitant. A backend parameter in savefig() is a big API promise. I really don't claim to understand the whole backend machinery, but, setting the backend only for the savefig() call feels too easy given that we've been jumping a lot of hoops to delay backend selection. Is this really a fully working solution that can live up to the API promised?

Does nothing we do in any plotting command (now or in the future) depend on the backend? Otherwise just setting the backend in savefig() is not equivalent to setting the backend earlier, and that would be quite surprising.
Following a similar logic, can we then equally do plt.show(backend='QtAgg')?
Would a context manager for backends be a reasonable alternative.
Do we need checks that the format/extension and the backend are compatible?

tacaswell · 2019-10-27T20:54:58Z

lib/matplotlib/backend_bases.py

+        else:
+            # Return a default canvas for the requested format, if it exists.
+            canvas_class = get_registered_canvas_class(fmt)
+            if not hasattr(canvas_class, f"print_{fmt}"):


I think this is in the wrong block of the if/elif/else.

oops, fixed

That probably means that a unit test should be written for this :)

fair enough, done

anntzer · 2019-10-27T21:01:06Z

re @timhoffm:

Does nothing we do in any plotting command (now or in the future) depend on the backend? Otherwise just setting the backend in savefig() is not equivalent to setting the backend earlier, and that would be quite surprising.

I believe not (the backend-dependent logic is in draw(), which is only called by savefig()).

Following a similar logic, can we then equally do plt.show(backend='QtAgg')?

Backend switching is subject to the same rules as use() (i.e. you cannot switch to an interactive backend requiring a GUI event loop once another GUI event loop is running). But switching to a noninteractive backend is fine (and the intended use case) -- note that we already implicitly do so for printing to pdf/ps/svg; this kwarg only makes it explicit and allows you to switch to backend_pgf rather than backend_pdf when printing to pdf.

Would a context manager for backends be a reasonable alternative.

I don't think there is anything else one would want to do within the context manager other than doing the save, which suggests that factoring out the backend switching is not worth it.

Do we need checks that the format/extension and the backend are compatible?

This has been added per @tacaswell's suggestion.

timhoffm · 2019-10-28T00:36:46Z

@anntzer thanks for the clarification.

I believe not (the backend-dependent logic is in draw(), which is only called by savefig()).

Are use cases affected that use an intermediate draw to get some position information and use that to position subsequent elements?

Backend switching is subject to the same rules as use() (i.e. you cannot switch to an interactive backend requiring a GUI event loop once another GUI event loop is running). But switching to a noninteractive backend is fine (and the intended use case)

Something like this should be explicitly mentioned in the docstring of the backend parameter; maybe even with a list of supported builtin backends.

The other points are ok.

anntzer · 2019-10-28T07:59:11Z

Are use cases affected that use an intermediate draw to get some position information and use that to position subsequent elements?

You'd run into the same issues (if any) as if saving to pdf from an interactive canvas, so nothing new.

Something like this should be explicitly mentioned in the docstring of the backend parameter; maybe even with a list of supported builtin backends.

done.

ArchangeGabriel · 2019-10-28T10:48:03Z

@anntzer Thanks for this work! Does the PR include a savefig.backend rcParams (it does not seems so), and if not could it be possible to add one?

anntzer · 2019-10-28T10:53:27Z

It doesn't and fwiw I still don't like the idea.

jklymak · 2019-10-28T16:39:24Z

lib/matplotlib/backend_bases.py

+        backend : str, optional
+            When set, forcibly use this non-interactive backend for rendering.
+            This can be either a standard backend name ("agg", "pdf", "pgf",
+            "ps", "svg") or a custom backend name ("module://...").


This could use a comment as to why we would ever want to do this. I'm not sure I understand from the PR what the goal is, so I can imagine users trying to dutifully use this keyword and getting themselves into a mess.

jklymak · 2019-10-28T19:05:06Z

lib/matplotlib/backend_bases.py

+            "ps", "svg") or a custom backend name ("module://...").  The main
+            use case of this parameter is to render to a format using a backend
+            that is neither the current backend, nor the default backend for
+            this format, e.g. for rendering pdfs using the pgf backend.


I'm still not clear. Are there other examples, like cairo instead of agg etc? If there is just one use case, I don't think this should get such a generic sounding kwarg name. If there are other cases, I'm confused about which ones are allowed. If I save to png, can I use pgf? Can I use the pdf backend to save to svg? Where are the compatibilities documented?

Indeed, you can also use cairo (either the builtin, so "cairo", or mplcairo ("module://mplcairo.base")) to save to any format.
For the builtin backends the compat table is at https://matplotlib.org/devdocs/tutorials/introductory/usage.html#the-builtin-backends (except that pgf is missing -- will open a separate PR for that -- now at #15555).

OK, thats more clear. I wonder if we change the kwarg to renderer and refer to this table somehow?

renderer: str, optional Use a non-default backend to render the file, i.e. `renderer='cairo'` for a png rather than the default 'agg' backend, or 'pgf' for a PDF instead of the default 'pdf'. See :doc:`/tutorials/introductory/usage` for a list of valid backends for each file format. Note custom backends can be referenced as "module://...".

BTW just to be clear, I'm balking at "backend" because the user will already have likely been subjected to the confusing idea that they have to select a backend, and then see this kwarg and assume the have to make it match up somehow. I think we should try and be clear that 99.9% of the time the user should not need to use this kwarg.

The doc sounds good, mostly used your suggestion with minor edits.
The argument matches the argument to matplotlib.use(), so I think it makes sense to keep the same argument name, so I'd still prefer backend here.

and added "Note that the default backend is normally sufficient."

Sounds good (though you didn't push anything yet, right?)

oops, missed the push, done now

tacaswell · 2019-10-29T06:39:45Z

Doc failures look real:

/home/circleci/project/lib/matplotlib/figure.py:docstring of matplotlib.figure.Figure.savefig:98: WARNING: Unknown target name: "the-builtin-backends".
/home/circleci/project/lib/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:98: WARNING: Unknown target name: "the-builtin-backends".
/home/circleci/project/lib/matplotlib/backend_bases.py:docstring of matplotlib.backend_bases.FigureCanvasBase.print_figure:42: WARNING: Unknown target name: "the-builtin-backends".

tacaswell

👍 modulo fixing the doc build

This makes it easier e.g. to test the pgf backend without globally switching the backend.

anntzer · 2019-10-29T08:45:00Z

doc build fixed

tacaswell reviewed Oct 27, 2019

View reviewed changes

lib/matplotlib/backend_bases.py Show resolved Hide resolved

tacaswell added this to the v3.3.0 milestone Oct 27, 2019

anntzer force-pushed the backendsavefigkwarg branch from 6650f21 to f647d15 Compare October 27, 2019 20:53

tacaswell reviewed Oct 27, 2019

View reviewed changes

anntzer force-pushed the backendsavefigkwarg branch from f647d15 to 7852a8f Compare October 27, 2019 20:56

anntzer force-pushed the backendsavefigkwarg branch from 7852a8f to 9fd5da5 Compare October 28, 2019 07:59

anntzer force-pushed the backendsavefigkwarg branch from 9fd5da5 to d001e38 Compare October 28, 2019 15:03

jklymak reviewed Oct 28, 2019

View reviewed changes

anntzer force-pushed the backendsavefigkwarg branch from d001e38 to ab74e58 Compare October 28, 2019 18:13

jklymak reviewed Oct 28, 2019

View reviewed changes

anntzer force-pushed the backendsavefigkwarg branch from ab74e58 to bfe34be Compare October 28, 2019 21:19

jklymak approved these changes Oct 28, 2019

View reviewed changes

tacaswell approved these changes Oct 29, 2019

View reviewed changes

Add a backend kwarg to savefig.

154a312

This makes it easier e.g. to test the pgf backend without globally switching the backend.

anntzer force-pushed the backendsavefigkwarg branch from bfe34be to 154a312 Compare October 29, 2019 08:32

NelleV merged commit 3272f8c into matplotlib:master Oct 30, 2019

anntzer deleted the backendsavefigkwarg branch October 30, 2019 10:17

This was referenced Sep 15, 2024

[FR] Setting PDF backend in matplotlibrc/style #13994

Closed

Update pgf tutorial #28824

Open

Uh oh!

Add a backend kwarg to savefig. #15536

Add a backend kwarg to savefig. #15536

Uh oh!

Conversation

anntzer commented Oct 27, 2019

PR Summary

PR Checklist

Uh oh!

Uh oh!

tacaswell commented Oct 27, 2019

Uh oh!

anntzer commented Oct 27, 2019

Uh oh!

timhoffm commented Oct 27, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer commented Oct 27, 2019

Uh oh!

timhoffm commented Oct 28, 2019

Uh oh!

anntzer commented Oct 28, 2019

Uh oh!

ArchangeGabriel commented Oct 28, 2019

Uh oh!

anntzer commented Oct 28, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anntzer Oct 28, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jklymak Oct 28, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tacaswell commented Oct 29, 2019

Uh oh!

tacaswell left a comment

Choose a reason for hiding this comment

Uh oh!

anntzer commented Oct 29, 2019

Uh oh!

Uh oh!

timhoffm commented Oct 27, 2019 •

edited

Loading

anntzer Oct 28, 2019 •

edited

Loading

jklymak Oct 28, 2019 •

edited

Loading