This was vague to avoid having to talk about prompt's inputhooks as well.

The current statement is a bit thin:

In this case, you are responsible for ensuring that the event loop is running to have responsive figures.

I guess only a tiny fraction of our users know what the event loop is, and even fewer whether they have to start it and if so how. I know that the answer is a bit more complex, but I think we can give more guidance.

Background: I was asked how to do this if one has N figures (in a simple script), each shown with plt.show(block=False) and in the end wants to start the event loop so that they become responsive. My answer was put fig.canvas.manager.mainloop() at the end. But thinking again, possibly the better answer would be: Don't call show on all the figures individually, but rather use a final plt.show() to show all collected figures. Right now, I can't think of a scenario where one would use block=False and then have to explicitly start the event loop yourself later. Do you have one?

A loop where you create / show figures, call plt.pause(N) / otherwise spin the eventloop, and then have a final plt.show(block=True) at the end to block until all of the figures are closed.

Is there a longer guide to this somewhere we can link out to?

Not that I'm aware of.

To collect use cases for plt.show(block=False)

• plt.show(block=False); plt.pause(n) to run the event loop for a limited time.
• plt.show(block=False); ... plt.show(block=False); ... plt.show(); to show multiple figures - but usually better done by not calling the intermediate shows at all.
• plt.show(block=False); ... plt.show(block=False); do_something(); fig.canvas.manager.mainloop(), where do_something() could e.g. reach for the windows and arrange them in a specific way.
• in ipython to, which does some magic behind the scenes to run the event loop but still not block.
• ... more ideas?

I guess this is somewhat discussed at https://matplotlib.org/stable/users/explain/figure/interactive.html, and https://matplotlib.org/stable/users/explain/figure/interactive_guide.html and in particular https://matplotlib.org/stable/users/explain/figure/interactive_guide.html#blocking-the-prompt So maybe just linking that here would help?

Semi-OT: maybe we have to rewrite/reframe the "interactive" docs at some time

• they have been written with a prompt or script workflow in mind and read a bit awkward for people using notebooks.

• "interactive" is used with several meanings and is thus confusing, at least

  • a basic figure redraw for figure window size changes - a user would likely not call this "interactive" but it ties into the technical mechanisms since it needs an event loop.
  • simple zoom/pan/mouse coordinates
  • the matplotlib event system
  • pyplot "interactive mode", i.e. immediate non-blocking showing of a figure and continuous updates on additional plot commands
  • more refined user-interactivity like ploty has (tooltips, data selection, connected plots, etc.) while one can build that through the event system above, IMO the difference is that the event system is low level infrastructure, and it's quite cumbersome to build interactivity that way. We don't have high-level api that would make this reasonably simple to end users (read: you have to be rather a software developer than a (data) scientist to do that)

For sure those docs are very dated. But they do explain blocking etc so linking them would be of some value in my opinion.

Semi-OT: maybe we have to rewrite/reframe the "interactive" docs at some time

Xref: #28722

The first three bullet points should be grouped into one: you want windows to pop up and update while some other (slow) loop is running. e.g.

fig, ax = plt.subplots()
ln, = ax.plot([], [])
plt.show(block=False)
old_data = None
for step in compute_loop:
 new_data = expensive_compute(step, old_data)
 ln.set_data(*new_data)
 plt.pause(0) # or fig.canvas.manager.mainloop() or fig.canvas.flush_events()
 old_data = new_data

Add as much complexity of only updating the plot ever N, having multiple figures, passing in a callback, ..., but I think that is the minimal pseudo-code.

The first three bullet points should be grouped into one

While they rely on the same underlying technology, these are quite different from a user perspective - which is what counts for our user docs. Being able to resize your window and expecting that the content adapts, is a natural expectation for GUIs and no user would regard this explicitly as "interactive" (conversely not responding to are window resize would be considered "broken"). That's quite different from "I can zoom into the data", and again quite different from "I can write callbacks to respond to user actions".