Activity

1. jamesbraza

   added

   Documentation

   on Dec 2, 2022
2. tacaswell commented on Dec 2, 2022

   

   tacaswell

   on Dec 2, 2022

   Member

   More actions

   The simplest fix is that we should be using a xref there instead of a code literal https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.draw_idle.

   The core of the problem is "draw" is a good name for things (short, clear, well known, good analogy) which is why we use it in 3 non-interchangable places.

   1. Artist.draw(renderer) https://matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.draw.html which is the visitor-pattern method we call as we cascade down the artist tree when rendering the Figure. This is a method on every Ariist and is probably the most non-negotiable part of the API that makes an object a valid artist (in practice there are like a dozen methods we use, but I think all of those could be made optional)
   2. FigureCanvasBase.draw() https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.draw which is a method on the Canvas. Note it take no arguements and it's primary job is to fabricate the renderer (how ever that needs to be done for the given backend) and then call self.fig.draw(new_renderer).
   3. plt.draw() which is an "application" level tool aimed at people working in a prompt. In this case we are assuming something is managing the GUI event loop and watching if the figures are stale so to get a rerendering that the user can see, all we have to do is mark is request a draw_idle

   In addition to the two library level methods there are "lazy" pairs:

   1. fig.draw_without_rendering() https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure.draw_without_rendering which is only on Figure objects which will walk the draw tree and turn the crank on all of the Matplotlib side things (doing deferred limit updates etc), but will not actually generate any output (it does this by using the normal Figure.draw with a no-op renderer)
   2. FigureCanvasBase.draw_idle which till the UI to the next time it is idle to please re-render the figure. This is useful because it can be used to effectively de-bounce many many commands so it is safe to use in library code where you want to be able to batch updates. https://matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.draw_idle
3. hukaidong commented on Dec 2, 2022

   

   hukaidong

   on Dec 2, 2022

   Contributor

   More actions

   The simplest fix is that we should be using a xref there instead of a code literal matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.draw_idle.

   The core of the problem is "draw" is a good name for things (short, clear, well known, good analogy) which is why we use it in 3 non-interchangable places.

   1. Artist.draw(renderer) matplotlib.org/stable/api/_as_gen/matplotlib.artist.Artist.draw.html which is the visitor-pattern method we call as we cascade down the artist tree when rendering the Figure. This is a method on every Ariist and is probably the most non-negotiable part of the API that makes an object a valid artist (in practice there are like a dozen methods we use, but I think all of those could be made optional)
   2. FigureCanvasBase.draw() matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.draw which is a method on the Canvas. Note it take no arguements and it's primary job is to fabricate the renderer (how ever that needs to be done for the given backend) and then call self.fig.draw(new_renderer).
   3. plt.draw() which is an "application" level tool aimed at people working in a prompt. In this case we are assuming something is managing the GUI event loop and watching if the figures are stale so to get a rerendering that the user can see, all we have to do is mark is request a draw_idle

   In addition to the two library level methods there are "lazy" pairs:

   1. fig.draw_without_rendering() matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure.draw_without_rendering which is only on Figure objects which will walk the draw tree and turn the crank on all of the Matplotlib side things (doing deferred limit updates etc), but will not actually generate any output (it does this by using the normal Figure.draw with a no-op renderer)
   2. FigureCanvasBase.draw_idle which till the UI to the next time it is idle to please re-render the figure. This is useful because it can be used to effectively de-bounce many many commands so it is safe to use in library code where you want to be able to batch updates. matplotlib.org/stable/api/backend_bases_api.html#matplotlib.backend_bases.FigureCanvasBase.draw_idle

   For the solution of create a xref link from fig.canvans.draw_idle, I think put a "See Also" section underneath with draw_idle and keep origin would be a better choice? I checked around but don't think sphinx provide a way to make a reference with customed code segment. At the sametime, only saying draw_idle or saying backend_bases.FigureCanvasBase.draw_idle will confuse the audience who is visiting this page.
4. github-actions commented on Jan 26, 2026

   

   github-actionsBot

   on Jan 26, 2026 – with GitHub Actions

   More actions

   This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!
5. github-actions

   added

   status: inactiveMarked by the “Stale” Github ActionMarked by the “Stale” Github Action

   on Jan 26, 2026
6. timhoffm commented on Jan 26, 2026

   

   timhoffm

   on Jan 26, 2026

   Member

   More actions

   Semi-OT: Is it worth renaming draw_idle? I'm also confused by the many draw semantics everytime I look into this. Alternatives could be:

   • schedule_draw
   • request_draw
   • draw_when_idle
   • ...

   draw_idle would then be discouraged, but not plan for removal.

   Reacted by James Braza
7. timhoffm

   added

   keepItems to be ignored by the “Stale” Github ActionItems to be ignored by the “Stale” Github Action

   and removed

   status: inactiveMarked by the “Stale” Github ActionMarked by the “Stale” Github Action

   on Jan 26, 2026
8. jamesbraza commented on Jan 26, 2026

   

   jamesbraza

   on Jan 26, 2026

   ContributorAuthor

   More actions

   I like schedule_ or request_ -- much clearer and intuitive. The concept of "idle" is muddled a bit imo
9. timhoffm commented on Feb 8, 2026

   

   timhoffm

   on Feb 8, 2026

   Member

   More actions

   Note: renaming is a bit more tricky, as this is Backend API, so we'd have to check for downstream backends whether they define the new or old method and call it appropriately. Not that it's not doable, but one needs to take some extra care.
10. timhoffm

    added

    topic: backends

    on Feb 26, 2026