Added keyword 'clear' for figure with test and what's new entry

DietBru · DietBru · commit 92df340d6ea9 · 2016-12-27T18:44:38.000+01:00
diff --git a/doc/users/whats_new/figure_new_clear_keyword.rst b/doc/users/whats_new/figure_new_clear_keyword.rst
@@ -0,0 +1,32 @@
+New parameter `clear` for :func:`~matplotlib.pyplot.figure`
+-----------------------------------------------------------
+
+When the pyplot's function :func:`~matplotlib.pyplot.figure` is called
+with a ``num`` parameter, a new window is only created if no existing
+window with the same value exists. A new bool parameter `clear` was
+added for explicitly clearing its existing contents. This is particularly
+useful when utilized in interactive sessions. Since
+:func:`~matplotlib.pyplot.subplots` also accepts keyword arguments
+from :func:`~matplotlib.pyplot.figure`, it can also be used there::
+
+   import matplotlib.pyplot as plt
+   
+   fig0 = plt.figure(num=1)
+   fig0.suptitle("A fancy plot")
+   print("fig0.texts: ", [t.get_text() for t in fig0.texts])
+   
+   fig1 = plt.figure(num=1, clear=False)  # do not clear contents of window
+   fig1.text(0.5, 0.5, "Really fancy!")
+   print("fig0 is fig1: ",  fig0 is fig1)
+   print("fig1.texts: ", [t.get_text() for t in fig1.texts]) 
+  
+   fig2, ax2 = plt.subplots(2, 1, num=1, clear=True)  # clear contents
+   print("fig0 is fig2: ",  fig0 is fig2)  
+   print("fig2.texts: ", [t.get_text() for t in fig2.texts])
+
+   # The output:
+   # fig0.texts:  ['A fancy plot']
+   # fig0 is fig1:  True
+   # fig1.texts:  ['A fancy plot', 'Really fancy!']
+   # fig0 is fig2:  True
+   # fig2.texts:  []
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -431,6 +431,7 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
            edgecolor=None,  # defaults to rc figure.edgecolor
            frameon=True,
            FigureClass=Figure,
+           clear=False,
            **kwargs
            ):
     """
@@ -457,10 +458,19 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
         resolution of the figure. If not provided, defaults to rc figure.dpi.
 
     facecolor :
-        the background color. If not provided, defaults to rc figure.facecolor
+        the background color. If not provided, defaults to rc figure.facecolor.
 
     edgecolor :
-        the border color. If not provided, defaults to rc figure.edgecolor
+        the border color. If not provided, defaults to rc figure.edgecolor.
+
+    frameon : bool, optional, default: True
+        If False, suppress drawing the figure frame.
+
+    FigureClass : class derived from matplotlib.figure.Figure
+        Optionally use a custom Figure instance.
+
+    clear : bool, optional, default: False
+        If True and the figure already exists, then it is cleared.
 
     Returns
     -------
@@ -558,6 +568,9 @@ def make_active(event):
         if _INSTALL_FIG_OBSERVER:
             fig.stale_callback = _auto_draw_if_interactive
 
+    if clear:
+        figManager.canvas.figure.clear()
+
     return figManager.canvas.figure
 
 
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -51,6 +51,24 @@ def test_fignum_exists():
     assert_equal(plt.fignum_exists(4), False)
 
 
+@cleanup
+def test_clf_keyword():
+   # test if existing figure is cleared with figure() and subplots()
+   fig0 = plt.figure(num=1)
+   fig0.suptitle("A fancy plot")
+   assert_equal([t.get_text() for t in fig0.texts], ["A fancy plot"])
+
+   fig1 = plt.figure(num=1, clear=False)
+   fig1.text(0.5, 0.5, "Really fancy!")
+   assert_true(fig0 is fig1)
+   assert_equal([t.get_text() for t in fig1.texts],
+                ["A fancy plot", 'Really fancy!'])
+
+   fig2, ax2 = plt.subplots(2, 1, num=1, clear=True)
+   assert_true(fig0 is fig2)
+   assert_equal([t.get_text() for t in fig2.texts], [])
+
+
 @image_comparison(baseline_images=['figure_today'])
 def test_figure():
     # named figure support
