Add option to gcf/gca to disable new figure/axes creation.

anntzer · anntzer · commit ed8cbbd44940 · 2021-08-01T00:30:06.000+02:00
This provides a relatively more user-friendly way to check whether a
current figure/axes exists.  (`_pylab_helpers.Gcf.get_active` is way too
"internal".)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1479,15 +1479,25 @@ def sca(self, a):
         return a
 
     @docstring.dedent_interpd
-    def gca(self, **kwargs):
+    def gca(self, *, can_be_new=True, **kwargs):
         """
-        Get the current Axes, creating one if necessary.
+        Get the current Axes.
 
-        The following kwargs are supported for ensuring the returned Axes
-        adheres to the given projection etc., and for Axes creation if
-        the active Axes does not exist:
+        Parameters
+        ----------
+        can_be_new : bool, default: True
+            *can_be_new* controls this method's behavior if there is no current
+            Axes: a new one is created if *can_be_new* is True (the default);
+            None is returned if *can_be_new* is False.
 
-        %(Axes:kwdoc)s
+        Other Parameters
+        ----------------
+        **kwargs
+            The kwargs listed below are supported for ensuring the returned
+            Axes adheres to the given projection etc., and for Axes creation if
+            the active Axes does not exist.  This behavior is deprecated.
+
+            %(Axes:kwdoc)s
         """
         if kwargs:
             _api.warn_deprecated(
@@ -1499,10 +1509,9 @@ def gca(self, **kwargs):
                 "new axes with default keyword arguments. To create a new "
                 "axes with non-default arguments, use plt.axes() or "
                 "plt.subplot().")
-        if self._axstack.empty():
-            return self.add_subplot(1, 1, 1, **kwargs)
-        else:
-            return self._axstack()
+        return (self._axstack() if not self._axstack.empty() else
+                self.add_subplot(1, 1, 1, **kwargs) if can_be_new else
+                None)
 
     def _gci(self):
         # Helper for `~matplotlib.pyplot.gci`.  Do not use elsewhere.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -815,18 +815,21 @@ def _auto_draw_if_interactive(fig, val):
             fig.canvas.draw_idle()
 
 
-def gcf():
+def gcf(*, can_be_new=True):
     """
     Get the current figure.
 
-    If no current figure exists, a new one is created using
-    `~.pyplot.figure()`.
+    Parameters
+    ----------
+    can_be_new : bool, default: True
+        *can_be_new* controls this method's behavior if there is no current
+        figure: a new one is created with `~.pyplot.figure()` if *can_be_new*
+        is True (the default); None is returned if *can_be_new* is False.
     """
     manager = _pylab_helpers.Gcf.get_active()
-    if manager is not None:
-        return manager.canvas.figure
-    else:
-        return figure()
+    return (manager.canvas.figure if manager is not None else
+            figure() if can_be_new else
+            None)
 
 
 def fignum_exists(num):
@@ -2486,8 +2489,8 @@ def figtext(x, y, s, fontdict=None, **kwargs):
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @_copy_docstring_and_deprecators(Figure.gca)
-def gca(**kwargs):
-    return gcf().gca(**kwargs)
+def gca(*, can_be_new=True, **kwargs):
+    return gcf().gca(can_be_new=can_be_new, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -64,6 +64,7 @@ def test_align_labels():
 def test_figure_label():
     # pyplot figure creation, selection, and closing with label/number/instance
     plt.close('all')
+    assert plt.gcf(can_be_new=False) is None
     fig_today = plt.figure('today')
     plt.figure(3)
     plt.figure('tomorrow')
@@ -150,6 +151,8 @@ def test_figure_legend():
 def test_gca():
     fig = plt.figure()
 
+    assert plt.gca(can_be_new=False) is None
+
     with pytest.raises(TypeError):
         assert fig.add_axes() is None
 
