ENH: draw no output #19968
ENH: draw no output #19968
Conversation
There was a problem hiding this comment.
I'm definitely +1 on this addition. It would be good to have a single, easy-to-understand, public place to point people that need this (as discussed in gitter, I get a large number of requests that boil down to people that need to make a figure, measure the size of some artists, then remake the figure with an "optimal" figure size).
Some thoughts:
draw has basically grown to do "mean" two things:
- crawl the artist tree
- actually do things involving the renderer
However a new user won't have the intuition that we do that (2) is something that historically we abuse "draw" to do, so maybe we should consider not even putting "draw" in the name? Or at least name the new method something that doesn't boil down to "draw but don't draw" maybe something like finalize_artists, or something more semantically on the nose like finalize_layout.
While there are many places this function should probably be called now (in both tests and docs) I think it's probably fine to do that piecemeal moving forward.
| either the screen or a file. This is useful for determining the final | ||
| position of artists on the figure that require a draw like text. | ||
| This could be accomplished via ``fig.canvas.draw()`` but that is | ||
| not user-facing, so a new method on `.Figure.draw_no_output` is provided. |
There was a problem hiding this comment.
I don't agree that fig.cavas.draw() is not user facing, we use it through out the examples and tutorials! I think the benefit here is that draw_on_output does not have any side effects out side of the Figure (where as draw may update a GUI or in the case of (iirc) the SVG backend require a file to be open), is marginally faster (due to the renderer.draw_* methods being stubbed out to no-ops), and is "at the top level" on the Figure object.
There was a problem hiding this comment.
Fair enough. All I meant by that is unless you are making a GUI or a backend you never need to know about the canvas.
I guess to suggest a heuristic to resolve the tension above: if we want users to know about and actively use an object in the normal course of things, we should guide them to it by removing top-level methods. In the case of "axis" it is arguably useful for the user to know about the axis objects and manipulate them directly, so it's probably worth removing some of the shadowing methods on "axes". For canvas I don't think we need any users to call methods on the canvas, unless of course they are making a GUI, so in this case it makes sense to bubble the method up.
I'll change the wording (definitely fewer side effects is another great reason to switch), look into moving the implementation to the public method.
We do use fig.canvas.draw a lot, so some follow up PRs would be great. Probably a good first issue activity.
There was a problem hiding this comment.
New text:
Rarely, the user will want to trigger a draw without making output to
either the screen or a file. This is useful for determining the final
position of artists on the figure that require a draw like text.
This could be accomplished via ``fig.canvas.draw()`` but has side effects,
sometimes requires an open file, and is documented on an object most users
do not need to access. The `.Figure.draw_no_output` is provided to trigger
a draw without pushing to the final output with fewer side effects.
lib/matplotlib/figure.py
Outdated
| Draw the figure with no output. Useful to get the final size of | ||
| artists that require a draw before their size is known (e.g. text). | ||
| """ | ||
| _no_output_draw(self) |
There was a problem hiding this comment.
If we are going to pull this up is it better to move the implementation here and replace our internal use of _no_output_draw with fig.draw_no_output()?
There was a problem hiding this comment.
Done - lets see if I made any mistakes via CI
304f0e5 to
15a62c1
Compare
e1be1d6 to
7e05975
Compare
PR Summary
Make user-facing
draw_no_outputto do the same thing asfig.canvas.drawPR Checklist
pytestpasses).flake8on changed files to check).flake8-docstringsand runflake8 --docstring-convention=all).doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).