MNT: defer calling gca or gcf unless we absolutely must

tacaswell · tacaswell · commit f26efd9b1526 · 2017-08-30T23:06:26.000-04:00
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -712,9 +712,31 @@ def draw(fig=None):
     fig.canvas.draw_idle()
 
 
+def _pop_or_gca(kwargs):
+    """
+    Internal helper function for getting an optional ax kwarg or gca
+
+    .. warning::
+
+       This mutates the input in place!
+    """
+    return kwargs.pop('ax', None) or gca()
+
+
+def _pop_or_gcf(kwargs):
+    """
+    Internal helper function for getting an optional fig kwarg or gcf
+
+    .. warning::
+
+       This mutates the input in place!
+    """
+    return kwargs.pop('fig', None) or gcf()
+
+
 @docstring.copy_dedent(Figure.savefig)
 def savefig(*args, **kwargs):
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     res = fig.savefig(*args, **kwargs)
     fig.canvas.draw_idle()   # need this if 'transparent=True' to reset colors
     return res
@@ -730,7 +752,7 @@ def ginput(*args, **kwargs):
 
     If *timeout* is negative, does not timeout.
     """
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     return fig.ginput(*args, **kwargs)
 
 
@@ -745,27 +767,27 @@ def waitforbuttonpress(*args, **kwargs):
 
     If *timeout* is negative, does not timeout.
     """
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     return fig.waitforbuttonpress(*args, **kwargs)
 
 
 # Putting things in figures
 
 @docstring.copy_dedent(Figure.text)
 def figtext(*args, **kwargs):
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     return fig.text(*args, **kwargs)
 
 
 @docstring.copy_dedent(Figure.suptitle)
 def suptitle(*args, **kwargs):
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     return fig.suptitle(*args, **kwargs)
 
 
 @docstring.copy_dedent(Figure.figimage)
 def figimage(*args, **kwargs):
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     return fig.figimage(*args, **kwargs)
 
 
@@ -804,7 +826,7 @@ def figlegend(*args, **kwargs):
        :func:`~matplotlib.pyplot.legend`
 
     """
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     return fig.legend(*args, **kwargs)
 
 
@@ -986,7 +1008,7 @@ def gca(**kwargs):
     --------
     matplotlib.figure.Figure.gca : The figure's gca method.
     """
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     return fig.gca(**kwargs)
 
 # More ways of creating axes:
@@ -1081,7 +1103,7 @@ def subplot(*args, **kwargs):
         warnings.warn("The subplot index argument to subplot() appears"
                       " to be a boolean. Did you intend to use subplots()?")
 
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     a = fig.add_subplot(*args, **kwargs)
     bbox = a.bbox
     byebye = []
@@ -1307,7 +1329,7 @@ def subplots_adjust(*args, **kwargs):
 
     The actual defaults are controlled by the rc file
     """
-    fig = kwargs.pop('fig', gcf())
+    fig = _pop_or_gcf(kwargs)
     fig.subplots_adjust(*args, **kwargs)
 
 
@@ -1417,7 +1439,7 @@ def title(s, *args, **kwargs):
         properties.
 
     """
-    return kwargs.pop('ax', gca()).set_title(s, *args, **kwargs)
+    return _pop_or_gca(kwargs).set_title(s, *args, **kwargs)
 
 ## Axis ##
 
@@ -1488,7 +1510,7 @@ def axis(*v, **kwargs):
         :func:`xlim`, :func:`ylim`
            For setting the x- and y-limits individually.
     """
-    return kwargs.pop('ax', gca()).axis(*v, **kwargs)
+    return _pop_or_gca(kwargs).axis(*v, **kwargs)
 
 
 def xlabel(s, *args, **kwargs):
@@ -1508,7 +1530,7 @@ def xlabel(s, *args, **kwargs):
         :func:`~matplotlib.pyplot.text`
             For information on how override and the optional args work
     """
-    return kwargs.pop('ax', gca()).set_xlabel(s, *args, **kwargs)
+    return _pop_or_gca(kwargs).set_xlabel(s, *args, **kwargs)
 
 
 def ylabel(s, *args, **kwargs):
@@ -1529,7 +1551,7 @@ def ylabel(s, *args, **kwargs):
             For information on how override and the optional args
             work.
     """
-    return kwargs.pop('ax', gca()).set_ylabel(s, *args, **kwargs)
+    return _pop_or_gca(kwargs).set_ylabel(s, *args, **kwargs)
 
 
 def xlim(*args, **kwargs):
@@ -1553,7 +1575,7 @@ def xlim(*args, **kwargs):
     The new axis limits are returned as a length 2 tuple.
 
     """
-    ax = kwargs.pop('ax', gca())
+    ax = _pop_or_gca(kwargs)
     if not args and not kwargs:
         return ax.get_xlim()
     ret = ax.set_xlim(*args, **kwargs)
@@ -1580,7 +1602,7 @@ def ylim(*args, **kwargs):
 
     The new axis limits are returned as a length 2 tuple.
     """
-    ax = kwargs.pop('ax', gca())
+    ax = _pop_or_gca(kwargs)
     if not args and not kwargs:
         return ax.get_ylim()
     ret = ax.set_ylim(*args, **kwargs)
@@ -1602,7 +1624,7 @@ def xscale(*args, **kwargs):
 
     %(scale_docs)s
     """
-    kwargs.pop('ax', gca()).set_xscale(*args, **kwargs)
+    _pop_or_gca(kwargs).set_xscale(*args, **kwargs)
 
 
 @docstring.dedent_interpd
@@ -1620,7 +1642,7 @@ def yscale(*args, **kwargs):
 
     %(scale_docs)s
     """
-    kwargs.pop('ax', gca()).set_yscale(*args, **kwargs)
+    _pop_or_gca(kwargs).set_yscale(*args, **kwargs)
 
 
 def xticks(*args, **kwargs):
@@ -1644,7 +1666,7 @@ def xticks(*args, **kwargs):
 
       xticks( arange(12), calendar.month_name[1:13], rotation=17 )
     """
-    ax = kwargs.pop('ax', gca())
+    ax = _pop_or_gca(kwargs)
 
     if len(args)==0:
         locs = ax.get_xticks()
@@ -1684,7 +1706,7 @@ def yticks(*args, **kwargs):
 
       yticks( arange(12), calendar.month_name[1:13], rotation=45 )
     """
-    ax = kwargs.pop('ax', gca())
+    ax = _pop_or_gca(kwargs)
 
     if len(args) == 0:
         locs = ax.get_yticks()
@@ -1757,7 +1779,7 @@ def rgrids(*args, **kwargs):
       lines, labels = rgrids( (0.25, 0.5, 1.0), ('Tom', 'Dick', 'Harry' )
 
     """
-    ax = kwargs.pop('ax', gca())
+    ax = _pop_or_gca(kwargs)
     if not isinstance(ax, PolarAxes):
         raise RuntimeError('rgrids only defined for polar axes')
     if len(args)==0:
@@ -1817,7 +1839,7 @@ def thetagrids(*args, **kwargs):
       # set the locations and labels of the radial gridlines and labels
       lines, labels = thetagrids( range(45,360,90), ('NE', 'NW', 'SW','SE') )
     """
-    ax = kwargs.pop('ax', gca())
+    ax = _pop_or_gca(kwargs)
     if not isinstance(ax, PolarAxes):
         raise RuntimeError('rgrids only defined for polar axes')
     if len(args)==0:
@@ -2473,9 +2495,8 @@ def _autogen_docstring(base):
 # return an image or a line.
 @_autogen_docstring(Axes.spy)
 def spy(Z, precision=0, marker=None, markersize=None, aspect='equal',
-        ax=None, **kwargs):
-    if ax is None:
-        ax = gca()
+        **kwargs):
+    ax = _pop_or_gca(kwargs)
     hold = kwargs.pop('hold', None)
     # allow callers to override the hold state by passing hold=True|False
     washold = ax._hold
