FIX: restore creating new axes via plt.subplot with different kwargs

tacaswell · tacaswell · commit 8f8cf4e84a12 · 2021-02-12T00:35:29.000-05:00
This adds a small amount of additional state to the Axes created via Figure.add_axes and Figure.add_subplot (which the other Axes creation methods eventually funnel through) to track the projection class and (processed) kwargs. We then use that state in `pyplot.subplot` to determine if we should re-use an Axes found at a given position or create a new one (and implicitly destroy the existing one). This also changes the behavior of `plt.subplot` when no kwargs are passed to return the Axes at the location without doing any matching of the kwargs. As part of this work we also fixed two additional bugs: - you can now force Axes "back to" rectilinear Axes by passing projection='rectilinear' - Axes3D instances can now be re-selected at all closes #19432 closes #10700
diff --git a/doc/api/next_api_changes/behavior/19438-TAC.rst b/doc/api/next_api_changes/behavior/19438-TAC.rst
@@ -0,0 +1,49 @@
+``plt.subplot`` re-selection without kwargs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The purpose of `pyplot.subplot` is to facilitate creating and
+re-selecting Axes in a Figure when working in the implicit pyplot API.
+When used to create Axes it is possible to select the projection
+(e.g. polar, 3D, or various cartographic projections) as well as to pass
+additional keyword arguments through to the Axes-subclass that is created.
+
+The first time `pyplot.subplot` is called for a given position in the
+Axes grid it is clear that the correct behavior is to create and
+return an Axes at the given position with the passed arguments
+(defaulting to a rectilinear Axes).  However, on n subsequent calls to
+`pyplot.subplot` the correct behavior is more subtle.  If an Axes exists
+at the requested location and has equivalent parameters the existing axes
+should be returned, but if the parameters are different the old Axes is removed
+from the Figure and a new Axes is created and returned.
+
+Due to an implementation detail, it was previously the case that for all
+Axes subclass, except for Axes3D, the axes would be deemed equivalent even
+if the projections were different.  Thus ::
+
+  ax1 = plt.subplot(1, 1, 1, projection='polar')
+  ax1 is plt.subplots(1, 1, 1)
+
+We are embracing this long standing behavior and in the case when no keyword
+arguments are passed to `pyplot.subplot` and there is an existing Axes
+at the grid position, the existing Axes is returned without consideration
+of the keywords used to create the Axes.
+
+Due to the previous implementation, if there was an existing Axes what
+was not rectilinear, passing ::
+
+  plt.subplot(projection='rectilinear')
+
+would return the existing Axes.  Now this will replace the existing Axes
+with a new rectilinear Axes.  To get the previous behavior, do not pass
+*projection*.
+
+Previously Axes3D could not be re-selected with `pyplot.subplot` due
+to an unrelated bug.  While Axes3D are now consistent with all other projections
+there is a change in behavior for ::
+
+  plt.subplot(projection='3d')  # create a 3D Axes
+
+  plt.subplot()                 # now returns existing 3D Axes
+                                # previously created new 2D Axes
+
+  plt.subplot(projection='rectilinear')  # to get a new 2D Axes
diff --git a/doc/users/next_whats_new/axes_kwargs_collision.rst b/doc/users/next_whats_new/axes_kwargs_collision.rst
@@ -3,19 +3,19 @@ Changes to behavior of Axes creation methods (``gca()``, ``add_axes()``, ``add_s
 
 The behavior of the functions to create new axes (`.pyplot.axes`,
 `.pyplot.subplot`, `.figure.Figure.add_axes`,
-`.figure.Figure.add_subplot`) has changed. In the past, these functions would
-detect if you were attempting to create Axes with the same keyword arguments as
-already-existing axes in the current figure, and if so, they would return the
-existing Axes. Now, these functions will always create new Axes. A special
-exception is `.pyplot.subplot`, which will reuse any existing subplot with a
-matching subplot spec. However, if there is a subplot with a matching subplot
-spec, then that subplot will be returned, even if the keyword arguments with
-which it was created differ.
+`.figure.Figure.add_subplot`) has changed.  In the past, these
+functions would detect if you were attempting to create Axes with the
+same keyword arguments as already-existing axes in the current figure,
+and if so, they would return the existing Axes.  Now, `.pyplot.axes`,
+`.figure.Figure.add_axes`, and `.figure.Figure.add_subplot` will
+always create new Axes.  `.pyplot.subplot` will continue reuse an
+existing Axes with a matching subplot spec and equal *kwargs*.
 
 Correspondingly, the behavior of the functions to get the current Axes
-(`.pyplot.gca`, `.figure.Figure.gca`) has changed. In the past, these functions
-accepted keyword arguments. If the keyword arguments matched an
-already-existing Axes, then that Axes would be returned, otherwise new Axes
-would be created with those keyword arguments. Now, the keyword arguments are
-only considered if there are no axes at all in the current figure. In a future
-release, these functions will not accept keyword arguments at all.
+(`.pyplot.gca`, `.figure.Figure.gca`) has changed.  In the past, these
+functions accepted keyword arguments.  If the keyword arguments
+matched an already-existing Axes, then that Axes would be returned,
+otherwise new Axes would be created with those keyword arguments.
+Now, the keyword arguments are only considered if there are no axes at
+all in the current figure. In a future release, these functions will
+not accept keyword arguments at all.
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -568,6 +568,7 @@ def add_axes(self, *args, **kwargs):
 
         if isinstance(args[0], Axes):
             a = args[0]
+            key = getattr(a, '_projection_init', ())
             if a.get_figure() is not self:
                 raise ValueError(
                     "The Axes must have been created in the present figure")
@@ -576,12 +577,13 @@ def add_axes(self, *args, **kwargs):
             if not np.isfinite(rect).all():
                 raise ValueError('all entries in rect must be finite '
                                  'not {}'.format(rect))
-            projection_class, kwargs = self._process_projection_requirements(
+            projection_class, pkw = self._process_projection_requirements(
                 *args, **kwargs)
 
             # create the new axes using the axes class given
-            a = projection_class(self, rect, **kwargs)
-        return self._add_axes_internal(a)
+            a = projection_class(self, rect, **pkw)
+            key = (projection_class, pkw)
+        return self._add_axes_internal(a, key)
 
     @docstring.dedent_interpd
     def add_subplot(self, *args, **kwargs):
@@ -694,6 +696,7 @@ def add_subplot(self, *args, **kwargs):
 
         if len(args) == 1 and isinstance(args[0], SubplotBase):
             ax = args[0]
+            key = getattr(ax, '_projection_init', ())
             if ax.get_figure() is not self:
                 raise ValueError("The Subplot must have been created in "
                                  "the present figure")
@@ -706,17 +709,20 @@ def add_subplot(self, *args, **kwargs):
             if (len(args) == 1 and isinstance(args[0], Integral)
                     and 100 <= args[0] <= 999):
                 args = tuple(map(int, str(args[0])))
-            projection_class, kwargs = self._process_projection_requirements(
+            projection_class, pkw = self._process_projection_requirements(
                 *args, **kwargs)
-            ax = subplot_class_factory(projection_class)(self, *args, **kwargs)
-        return self._add_axes_internal(ax)
+            ax = subplot_class_factory(projection_class)(self, *args, **pkw)
+            key = (projection_class, pkw)
+        return self._add_axes_internal(ax, key)
 
-    def _add_axes_internal(self, ax):
+    def _add_axes_internal(self, ax, key):
         """Private helper for `add_axes` and `add_subplot`."""
         self._axstack.push(ax)
         self._localaxes.push(ax)
         self.sca(ax)
         ax._remove_method = self.delaxes
+        # this is to support plt.subplot's re-selection logic
+        ax._projection_init = key
         self.stale = True
         ax.stale_callback = _stale_figure_callback
         return ax
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1072,10 +1072,10 @@ def cla():
 @docstring.dedent_interpd
 def subplot(*args, **kwargs):
     """
-    Add a subplot to the current figure.
+    Add an Axes to the current figure or retrieve an existing Axes.
 
-    Wrapper of `.Figure.add_subplot` with a difference in
-    behavior explained in the notes section.
+    This is a wrapper of `.Figure.add_subplot` which provides additional
+    behavior when working with the implicit API (see the notes section).
 
     Call signatures::
 
@@ -1142,8 +1142,8 @@ def subplot(*args, **kwargs):
 
     Notes
     -----
-    Creating a subplot will delete any pre-existing subplot that overlaps
-    with it beyond sharing a boundary::
+    Creating a new Axes will delete any pre-existing Axes that
+    overlaps with it beyond sharing a boundary::
 
         import matplotlib.pyplot as plt
         # plot a line, implicitly creating a subplot(111)
@@ -1156,18 +1156,19 @@ def subplot(*args, **kwargs):
     If you do not want this behavior, use the `.Figure.add_subplot` method
     or the `.pyplot.axes` function instead.
 
-    If the figure already has a subplot with key (*args*,
-    *kwargs*) then it will simply make that subplot current and
-    return it.  This behavior is deprecated. Meanwhile, if you do
-    not want this behavior (i.e., you want to force the creation of a
-    new subplot), you must use a unique set of args and kwargs.  The axes
-    *label* attribute has been exposed for this purpose: if you want
-    two subplots that are otherwise identical to be added to the figure,
-    make sure you give them unique labels.
+    If no *kwargs* are passed and there exists an Axes in the location
+    specified by *args* then that Axes will be returned rather than a new
+    Axes being created.
 
-    In rare circumstances, `.Figure.add_subplot` may be called with a single
-    argument, a subplot axes instance already created in the
-    present figure but not in the figure's list of axes.
+    If *kwargs* are passed and there exists an Axes in the location
+    specified by *args*, the projection type is the same, and the
+    *kwargs* match with the existing Axes, then the existing Axes is
+    returned.  Otherwise a new Axes is created with the specified
+    parameters.  We save a reference to the *kwargs* which we us
+    for this comparison.  If any of the values in *kwargs* are
+    mutable we will not detect the case where they are mutated.
+    In these cases we suggest using `.Figure.add_subplot` and the
+    explicit Axes API rather than the implicit pyplot API.
 
     See Also
     --------
@@ -1183,10 +1184,10 @@ def subplot(*args, **kwargs):
         plt.subplot(221)
 
         # equivalent but more general
-        ax1=plt.subplot(2, 2, 1)
+        ax1 = plt.subplot(2, 2, 1)
 
         # add a subplot with no frame
-        ax2=plt.subplot(222, frameon=False)
+        ax2 = plt.subplot(222, frameon=False)
 
         # add a polar subplot
         plt.subplot(223, projection='polar')
@@ -1199,7 +1200,27 @@ def subplot(*args, **kwargs):
 
         # add ax2 to the figure again
         plt.subplot(ax2)
+
+        # make the first axes "current" again
+        plt.subplot(221)
+
     """
+    proj_placeholder = object()
+    # sort out if the user passed us either polar or projection
+    # in principle we need to handle if *axes_class* is passed, but
+    # we will leave that validation to down stream code.  Here we will
+    # only normalize `polar=True` vs `projection='polar'` so we can decide
+    # if we should create a new Axes or return the existing one
+    projection = kwargs.get('projection', proj_placeholder)
+    polar = kwargs.pop('polar', proj_placeholder)
+    if polar is not proj_placeholder and polar:
+        # if we got mixed messages from the user, raise
+        if projection is not proj_placeholder and projection != 'polar':
+            raise ValueError(
+                f"polar={polar}, yet projection={projection!r}. "
+                "Only one of these arguments should be supplied."
+            )
+        kwargs['projection'] = projection = 'polar'
 
     # if subplot called without arguments, create subplot(1, 1, 1)
     if len(args) == 0:
@@ -1228,10 +1249,27 @@ def subplot(*args, **kwargs):
         (ax for ax in fig.axes
          if hasattr(ax, 'get_subplotspec') and ax.get_subplotspec() == key),
         None)
+    # if we found an axes at the right position sort out if we
+    # should re-use it
+    if ax is not None:
+        # sort out what projection and class would be created so we
+        # can tell if we should re-use an existing one
+        p_class, pkw = fig._process_projection_requirements(*args, **kwargs)
+        # if no projection or kwargs were passed, return the axes we
+        # found.
+        if projection is proj_placeholder and pkw == {}:
+            ax = ax
+        # if the axes class and kwargs are identical reuse the Axes
+        elif getattr(ax, '_projection_init', ()) == (p_class, pkw):
+            ax = ax
+        # otherwise we need to make a new one!
+        else:
+            ax = None
 
-    # If no existing axes match, then create a new one.
+    # if we do not want to re-use the existing Axes,
     if ax is None:
         ax = fig.add_subplot(*args, **kwargs)
+
     fig.sca(ax)
 
     bbox = ax.bbox
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -939,30 +939,32 @@ def test_subfigure_double():
     axsRight = subfigs[1].subplots(2, 2)
 
 
-def test_axes_kwargs():
-    # plt.axes() always creates new axes, even if axes kwargs differ.
-    plt.figure()
-    ax = plt.axes()
-    ax1 = plt.axes()
+def test_add_subplot_kwargs():
+    # fig.add_subplot() always creates new axes, even if axes kwargs differ.
+    fig = plt.figure()
+    ax = fig.add_subplot(1, 1, 1)
+    ax1 = fig.add_subplot(1, 1, 1)
     assert ax is not None
     assert ax1 is not ax
     plt.close()
 
-    plt.figure()
-    ax = plt.axes(projection='polar')
-    ax1 = plt.axes(projection='polar')
+    fig = plt.figure()
+    ax = fig.add_subplot(1, 1, 1, projection='polar')
+    ax1 = fig.add_subplot(1, 1, 1, projection='polar')
     assert ax is not None
     assert ax1 is not ax
     plt.close()
 
-    plt.figure()
-    ax = plt.axes(projection='polar')
-    ax1 = plt.axes()
+    fig = plt.figure()
+    ax = fig.add_subplot(1, 1, 1, projection='polar')
+    ax1 = fig.add_subplot(1, 1, 1)
     assert ax is not None
     assert ax1.name == 'rectilinear'
     assert ax1 is not ax
     plt.close()
 
+
+def test_add_axes_kwargs():
     # fig.add_axes() always creates new axes, even if axes kwargs differ.
     fig = plt.figure()
     ax = fig.add_axes([0, 0, 1, 1])
@@ -985,73 +987,3 @@ def test_axes_kwargs():
     assert ax1.name == 'rectilinear'
     assert ax1 is not ax
     plt.close()
-
-    # fig.add_subplot() always creates new axes, even if axes kwargs differ.
-    fig = plt.figure()
-    ax = fig.add_subplot(1, 1, 1)
-    ax1 = fig.add_subplot(1, 1, 1)
-    assert ax is not None
-    assert ax1 is not ax
-    plt.close()
-
-    fig = plt.figure()
-    ax = fig.add_subplot(1, 1, 1, projection='polar')
-    ax1 = fig.add_subplot(1, 1, 1, projection='polar')
-    assert ax is not None
-    assert ax1 is not ax
-    plt.close()
-
-    fig = plt.figure()
-    ax = fig.add_subplot(1, 1, 1, projection='polar')
-    ax1 = fig.add_subplot(1, 1, 1)
-    assert ax is not None
-    assert ax1.name == 'rectilinear'
-    assert ax1 is not ax
-    plt.close()
-
-    # plt.subplot() searches for axes with the same subplot spec, and if one
-    # exists, returns it, regardless of whether the axes kwargs were the same.
-    fig = plt.figure()
-    ax = plt.subplot(1, 2, 1)
-    ax1 = plt.subplot(1, 2, 1)
-    ax2 = plt.subplot(1, 2, 2)
-    ax3 = plt.subplot(1, 2, 1, projection='polar')
-    assert ax is not None
-    assert ax1 is ax
-    assert ax2 is not ax
-    assert ax3 is ax
-    assert ax.name == 'rectilinear'
-    assert ax3.name == 'rectilinear'
-    plt.close()
-
-    # plt.gca() returns an existing axes, unless there were no axes.
-    plt.figure()
-    ax = plt.gca()
-    ax1 = plt.gca()
-    assert ax is not None
-    assert ax1 is ax
-    plt.close()
-
-    # plt.gca() raises a DeprecationWarning if called with kwargs.
-    plt.figure()
-    with pytest.warns(
-            MatplotlibDeprecationWarning,
-            match=r'Calling gca\(\) with keyword arguments was deprecated'):
-        ax = plt.gca(projection='polar')
-    ax1 = plt.gca()
-    assert ax is not None
-    assert ax1 is ax
-    assert ax1.name == 'polar'
-    plt.close()
-
-    # plt.gca() ignores keyword arguments if an axes already exists.
-    plt.figure()
-    ax = plt.gca()
-    with pytest.warns(
-            MatplotlibDeprecationWarning,
-            match=r'Calling gca\(\) with keyword arguments was deprecated'):
-        ax1 = plt.gca(projection='polar')
-    assert ax is not None
-    assert ax1 is ax
-    assert ax1.name == 'rectilinear'
-    plt.close()
diff --git a/lib/matplotlib/tests/test_pyplot.py b/lib/matplotlib/tests/test_pyplot.py
