Deprecate passing extra arguments to Figure.add_axes

Co-authored-by: Thomas A Caswell <[email protected]>

Author: QuLogic

doc/api/next_api_changes/deprecations/25859-ES.rst

@@ -0,0 +1,5 @@
+Passing extra positional arguments to ``Figure.add_axes``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Positional arguments passed to `.Figure.add_axes` other than a rect or an
+existing ``Axes`` are currently ignored, and doing so is now deprecated.

lib/matplotlib/axes/_axes.py

@@ -392,8 +392,7 @@ def inset_axes(self, bounds, *, transform=None, zorder=5, **kwargs):
         # This puts the rectangle into figure-relative coordinates.
         inset_locator = _TransformedBoundsLocator(bounds, transform)
         bounds = inset_locator(self, None).bounds
-        projection_class, pkw = self.figure._process_projection_requirements(
-                bounds, **kwargs)
+        projection_class, pkw = self.figure._process_projection_requirements(**kwargs)
         inset_ax = projection_class(self.figure, bounds, zorder=zorder, **pkw)
 
         # this locator lets the axes move if in data coordinates.

lib/matplotlib/figure.py

@@ -621,22 +621,26 @@ def add_axes(self, *args, **kwargs):
             args = (kwargs.pop('rect'), )
 
         if isinstance(args[0], Axes):
-            a = args[0]
+            a, *extra_args = args
             key = a._projection_init
             if a.get_figure() is not self:
                 raise ValueError(
                     "The Axes must have been created in the present figure")
         else:
-            rect = args[0]
+            rect, *extra_args = args
             if not np.isfinite(rect).all():
-                raise ValueError('all entries in rect must be finite '
-                                 f'not {rect}')
-            projection_class, pkw = self._process_projection_requirements(
-                *args, **kwargs)
+                raise ValueError(f'all entries in rect must be finite not {rect}')
+            projection_class, pkw = self._process_projection_requirements(**kwargs)
 
             # create the new axes using the axes class given
             a = projection_class(self, rect, **pkw)
             key = (projection_class, pkw)
+
+        if extra_args:
+            _api.warn_deprecated(
+                "3.8",
+                name="Passing more than one positional argument to Figure.add_axes",
+                addendum="Any additional positional arguments are now ignored.")
         return self._add_axes_internal(a, key)
 
     @_docstring.dedent_interpd
@@ -762,8 +766,7 @@ 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, pkw = self._process_projection_requirements(
-                *args, **kwargs)
+            projection_class, pkw = self._process_projection_requirements(**kwargs)
             ax = projection_class(self, *args, **pkw)
             key = (projection_class, pkw)
         return self._add_axes_internal(ax, key)
@@ -1662,9 +1665,8 @@ def _gci(self):
                 return im
         return None
 
-    def _process_projection_requirements(
-            self, *args, axes_class=None, polar=False, projection=None,
-            **kwargs):
+    def _process_projection_requirements(self, *, axes_class=None, polar=False,
+                                         projection=None, **kwargs):
         """
         Handle the args/kwargs to add_axes/add_subplot/gca, returning::
 

lib/matplotlib/figure.pyi

@@ -232,7 +232,7 @@ class FigureBase(Artist):
     def gca(self) -> Axes: ...
     def _gci(self) -> ScalarMappable | None: ...
     def _process_projection_requirements(
-        self, *args, axes_class=None, polar=False, projection=None, **kwargs
+        self, *, axes_class=None, polar=False, projection=None, **kwargs
     ) -> tuple[type[Axes], dict[str, Any]]: ...
     def get_default_bbox_extra_artists(self) -> list[Artist]: ...
     def get_tightbbox(

lib/matplotlib/pyplot.py

@@ -1394,7 +1394,7 @@ def subplot(*args, **kwargs) -> Axes:
         if (ax.get_subplotspec() == key
             and (kwargs == {}
                  or (ax._projection_init
-                     == fig._process_projection_requirements(*args, **kwargs)))):
+                     == fig._process_projection_requirements(**kwargs)))):
             break
     else:
         # we have exhausted the known Axes and none match, make a new one!

lib/matplotlib/tests/test_figure.py

@@ -485,12 +485,21 @@ def test_invalid_figure_add_axes():
     with pytest.raises(TypeError, match="multiple values for argument 'rect'"):
         fig.add_axes([0, 0, 1, 1], rect=[0, 0, 1, 1])
 
-    _, ax = plt.subplots()
+    fig2, ax = plt.subplots()
     with pytest.raises(ValueError,
                        match="The Axes must have been created in the present "
                              "figure"):
         fig.add_axes(ax)
 
+    fig2.delaxes(ax)
+    with pytest.warns(mpl.MatplotlibDeprecationWarning,
+                      match="Passing more than one positional argument"):
+        fig2.add_axes(ax, "extra positional argument")
+
+    with pytest.warns(mpl.MatplotlibDeprecationWarning,
+                      match="Passing more than one positional argument"):
+        fig.add_axes([0, 0, 1, 1], "extra positional argument")
+
 
 def test_subplots_shareax_loglabels():
     fig, axs = plt.subplots(2, 2, sharex=True, sharey=True, squeeze=False)