Deprecate add_all parameter.

anntzer · anntzer · commit 3b4d7c49f796 · 2020-03-30T10:54:08.000+02:00
I'm not really sure there's a use case for not adding axes to the parent
figure (it was never used in the history of the library), and in any
case axes can always be removed with `ax.remove()`.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -402,3 +402,10 @@ The qt4agg and qt4cairo backends are deprecated.
 ``RendererWx.get_gc``
 ~~~~~~~~~~~~~~~~~~~~~
 This method is deprecated.  Access the ``gc`` attribute directly instead.
+
+*add_all* parameter in ``axes_grid``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The *add_all* parameter of `.axes_grid1.axes_grid.Grid`,
+`.axes_grid1.axes_grid.ImageGrid`, `.axes_grid1.axes_rgb.make_rgb_axes` and
+`.axes_grid1.axes_rgb.RGBAxes` is deprecated.  Axes are now always added to the
+parent figure, though they can be later removed with ``ax.remove()``.
diff --git a/lib/mpl_toolkits/axes_grid1/axes_grid.py b/lib/mpl_toolkits/axes_grid1/axes_grid.py
@@ -93,6 +93,7 @@ class Grid:
 
     _defaultAxesClass = Axes
 
+    @cbook._delete_parameter("3.3", "add_all")
     def __init__(self, fig,
                  rect,
                  nrows_ncols,
@@ -128,6 +129,7 @@ def __init__(self, fig,
             inches.
         add_all : bool, default: True
             Whether to add the axes to the figure using `.Figure.add_axes`.
+            This parameter is deprecated.
         share_all : bool, default: False
             Whether all axes share their x- and y-axis.  Overrides *share_x*
             and *share_y*.
@@ -343,6 +345,7 @@ class ImageGrid(Grid):
 
     _defaultCbarAxesClass = CbarAxes
 
+    @cbook._delete_parameter("3.3", "add_all")
     def __init__(self, fig,
                  rect,
                  nrows_ncols,
@@ -381,6 +384,7 @@ def __init__(self, fig,
             inches.
         add_all : bool, default: True
             Whether to add the axes to the figure using `.Figure.add_axes`.
+            This parameter is deprecated.
         share_all : bool, default: False
             Whether all axes share their x- and y-axis.
         aspect : bool, default: True
@@ -415,11 +419,18 @@ def __init__(self, fig,
         self._colorbar_size = cbar_size
         # The colorbar axes are created in _init_locators().
 
-        super().__init__(
-            fig, rect, nrows_ncols, ngrids,
-            direction=direction, axes_pad=axes_pad, add_all=add_all,
-            share_all=share_all, share_x=True, share_y=True, aspect=aspect,
-            label_mode=label_mode, axes_class=axes_class)
+        if add_all:
+            super().__init__(
+                fig, rect, nrows_ncols, ngrids,
+                direction=direction, axes_pad=axes_pad,
+                share_all=share_all, share_x=True, share_y=True, aspect=aspect,
+                label_mode=label_mode, axes_class=axes_class)
+        else:  # Only show deprecation in that case.
+            super().__init__(
+                fig, rect, nrows_ncols, ngrids,
+                direction=direction, axes_pad=axes_pad, add_all=add_all,
+                share_all=share_all, share_x=True, share_y=True, aspect=aspect,
+                label_mode=label_mode, axes_class=axes_class)
 
         if add_all:
             for ax in self.cbar_axes:
diff --git a/lib/mpl_toolkits/axes_grid1/axes_rgb.py b/lib/mpl_toolkits/axes_grid1/axes_rgb.py
@@ -5,6 +5,7 @@
 from .mpl_axes import Axes
 
 
+@cbook._delete_parameter("3.3", "add_all")
 def make_rgb_axes(ax, pad=0.01, axes_class=None, add_all=True, **kwargs):
     """
     Parameters
@@ -89,14 +90,16 @@ class RGBAxes:
 
     _defaultAxesClass = Axes
 
+    @cbook._delete_parameter("3.3", "add_all")
     def __init__(self, *args, pad=0, add_all=True, **kwargs):
         """
         Parameters
         ----------
         pad : float, default: 0
             fraction of the axes height to put as padding.
         add_all : bool, default: True
-            Whether to add the {rgb, r, g, b} axes to the figure
+            Whether to add the {rgb, r, g, b} axes to the figure.
+            This parameter is deprecated.
         axes_class : matplotlib.axes.Axes
 
         *args
@@ -108,8 +111,10 @@ def __init__(self, *args, pad=0, add_all=True, **kwargs):
         self.RGB = ax = axes_class(*args, **kwargs)
         if add_all:
             ax.get_figure().add_axes(ax)
+        else:
+            kwargs["add_all"] = add_all  # only show deprecation in that case
         self.R, self.G, self.B = make_rgb_axes(
-            ax, pad=pad, axes_class=axes_class, add_all=add_all, **kwargs)
+            ax, pad=pad, axes_class=axes_class, **kwargs)
         self._config_axes()
 
     def _config_axes(self, line_color='w', marker_edge_color='w'):
