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

tacaswell · QuLogic · tacaswell · commit 337dc3863d1e · 2021-02-17T23:38:13.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 Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
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,62 @@
+``plt.subplot`` re-selection without keyword arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 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.  This leaves open the question of what is "equivalent
+parameters".
+
+Due to an implementation detail, it was previously the case that for
+all Axes subclass, except for Axes3D, the Axes would be considered
+equivalent to a 2D rectilinear Axes, despite having different
+projections, if the kwargs (other than *projection* matched.  Thus ::
+
+  ax1 = plt.subplot(1, 1, 1, projection='polar')
+  ax1 is plt.subplots(1, 1, 1)
+
+We are embracing this long standing behavior to ensure that in the
+case when no keyword arguments (of any sort) are passed to
+`.pyplot.subplot` any existing Axes is returned, without consideration
+for key words used to initially create it.  This will cause a change
+in behavior when keywords were passed to the original axes ::
+
+  ax1 = plt.subplot(111, projection='polar', theta_offset=.75)
+  ax1 is is plt.subplots(1, 1, 1)      # new behavior
+  # ax1 is not plt.subplots(1, 1, 1)   # would make
+
+Similarly, if there was an existing Axes that was not rectilinear,
+passing ``projection='rectilinear'`` would return (usually) return the
+existing Axes: ::
+
+  ax1 = plt.subplot(projection='polar')
+  ax2 = plt.subplot(projection='rectilinear')
+  ax1 is not ax2     # new behavior
+  # ax1 is ax2       # old behavior
+
+
+To get the previous behavior, do not pass *projection* (or any keyword
+argument) to `.pyplot.subplot`.
+
+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, but
+                                # 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 to 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
@@ -567,6 +567,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")
@@ -575,12 +576,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):
@@ -693,6 +695,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")
@@ -705,17 +708,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)
+
     """
+    unset = 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', unset)
+    polar = kwargs.pop('polar', unset)
+    if polar is not unset and polar:
+        # if we got mixed messages from the user, raise
+        if projection is not unset 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:
@@ -1224,14 +1245,32 @@ def subplot(*args, **kwargs):
 
     # First, search for an existing subplot with a matching spec.
     key = SubplotSpec._from_subplot_args(fig, args)
-    ax = next(
-        (ax for ax in fig.axes
-         if hasattr(ax, 'get_subplotspec') and ax.get_subplotspec() == key),
-        None)
 
-    # If no existing axes match, then create a new one.
-    if ax is None:
+    for ax in fig.axes:
+        if hasattr(ax, 'get_subplotspec') and ax.get_subplotspec() == key:
+            # if we found an axes at the right position sort out if we
+            # should re-use it
+
+            # sort out what projection class and kwargs 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 projection kwargs were passed,
+            # return the axes we found with out checking anything
+            # else.
+            if projection is unset and pkw == {}:
+                break
+            # otherwise, only reuse if the axes class and kwargs are
+            # identical
+            elif getattr(ax, '_projection_init', ()) == (p_class, pkw):
+                break
+    else:
+        # in the case where we have exhausted the know Axes, make a
+        # new one!
         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
diff --git a/lib/matplotlib/tests/test_pyplot.py b/lib/matplotlib/tests/test_pyplot.py
