From dbccd04f9b1cf04e2ec8d8cc234d1d274439e733 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Tue, 13 Dec 2022 15:38:22 +0100 Subject: [PATCH] Backport PR #24607: DOC: tweak wording on Figure.show warning --- lib/matplotlib/figure.py | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 77d4b1fcf3dd..3c0218b9fe0e 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2619,18 +2619,25 @@ def show(self, warn=True): may only be shown briefly or not shown at all if you or your environment are not managing an event loop. - Proper use cases for `.Figure.show` include running this from a - GUI application or an IPython shell. - - If you're running a pure python shell or executing a non-GUI - python script, you should use `matplotlib.pyplot.show` instead, - which takes care of managing the event loop for you. + Use cases for `.Figure.show` include running this from a GUI + application (where there is persistently an event loop running) or + from a shell, like IPython, that install an input hook to allow the + interactive shell to accept input while the figure is also being + shown and interactive. Some, but not all, GUI toolkits will + register an input hook on import. See :ref:`cp_integration` for + more details. + + If you're in a shell without input hook integration or executing a + python script, you should use `matplotlib.pyplot.show` with + ``block=True`` instead, which takes care of starting and running + the event loop for you. Parameters ---------- warn : bool, default: True If ``True`` and we are not running headless (i.e. on Linux with an unset DISPLAY), issue warning when called on a non-GUI backend. + """ if self.canvas.manager is None: raise AttributeError(