diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 404179341264..f889c2d3b937 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1482,15 +1482,25 @@ def sca(self, a): return a @docstring.dedent_interpd - def gca(self, **kwargs): + def gca(self, *, create_if_none=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 + ---------- + create_if_none : bool, default: True + *create_if_none* controls this method's behavior if there is no + current Axes: a new one is created if *create_if_none* is True (the + default); None is returned if *create_if_none* 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( @@ -1502,10 +1512,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 create_if_none 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 index 7c29cb1b7ba1..b96d19d1434c 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -815,18 +815,22 @@ def _auto_draw_if_interactive(fig, val): fig.canvas.draw_idle() -def gcf(): +def gcf(*, create_if_none=True): """ Get the current figure. - If no current figure exists, a new one is created using - `~.pyplot.figure()`. + Parameters + ---------- + create_if_none : bool, default: True + *create_if_none* controls this method's behavior if there is no + current figure: a new one is created with `~.pyplot.figure()` + if *create_if_none* is True (the default); None is returned if + *create_if_none* 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 create_if_none else + None) def fignum_exists(num): @@ -954,6 +958,31 @@ def figlegend(*args, **kwargs): ## Axes ## +def gca(*, create_if_none=True, **kwargs): + """ + Get the current Axes. + + Parameters + ---------- + create_if_none : bool, default: True + *create_if_none* controls this functions's behavior if there is no + current Axes: a new one is created if *create_if_none* is True (the + default); None is returned if *create_if_none* is False. + + 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 + """ + fig = gcf(create_if_none=create_if_none) + return (None if fig is None + else fig.gca(create_if_none=create_if_none, **kwargs)) + + @docstring.dedent_interpd def axes(arg=None, **kwargs): """ @@ -2484,12 +2513,6 @@ def figtext(x, y, s, fontdict=None, **kwargs): return gcf().text(x, y, s, fontdict=fontdict, **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) - - # Autogenerated by boilerplate.py. Do not edit as changes will be lost. @_copy_docstring_and_deprecators(Figure._gci) def gci(): diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py index ccb1381fa5b5..1f6eec765600 100644 --- 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(create_if_none=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(create_if_none=False) is None + with pytest.raises(TypeError): assert fig.add_axes() is None diff --git a/tools/boilerplate.py b/tools/boilerplate.py index 46c8d3656373..6fd12ec3509e 100644 --- a/tools/boilerplate.py +++ b/tools/boilerplate.py @@ -203,7 +203,6 @@ def boilerplate_gen(): _figure_commands = ( 'figimage', 'figtext:text', - 'gca', 'gci:_gci', 'ginput', 'subplots_adjust',