Merge pull request #13599 from meeseeksmachine/auto-backport-of-pr-13590-on-v3.1.x

dstansby · web-flow · commit cae85665c5d4 · 2019-03-06T12:07:23.000Z
Backport PR #13590 on branch v3.1.x (Doc event loop requirements for Figure.show)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -411,6 +411,18 @@ def show(self, warn=True):
         :class:`~matplotlib.backend_bases.FigureManagerBase`, and
         will raise an AttributeError.
 
+        .. warning::
+            This does not manage an GUI event loop. Consequently, the figure
+            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.
+
         Parameters
         ----------
         warn : bool
