Deprecate undefined label_mode to Grid

Author: oscargus

doc/api/next_api_changes/deprecations/24071-OG.rst

@@ -0,0 +1,9 @@
+Passing undefined ``label_mode`` to ``Grid``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... is deprecated. This includes `mpl_toolkits.axes_grid1.axes_grid.Grid`,
+`mpl_toolkits.axes_grid1.axes_grid.AxesGrid`, and
+`mpl_toolkits.axes_grid1.axes_grid.ImageGrid` as well as the corresponding
+classes imported from `mpl_toolkits.axisartist.axes_grid`.
+
+Pass ``'keep'`` instead to get the same behavior.

lib/mpl_toolkits/axes_grid1/axes_grid.py

@@ -99,13 +99,14 @@ def __init__(self, fig,
             Whether all axes of a column share their x-axis.
         share_y : bool, default: True
             Whether all axes of a row share their y-axis.
-        label_mode : {"L", "1", "all"}, default: "L"
+        label_mode : {"L", "1", "all", "keep"}, default: "L"
             Determines which axes will get tick labels:
 
             - "L": All axes on the left column get vertical tick labels;
               all axes on the bottom row get horizontal tick labels.
             - "1": Only the bottom left axes is labelled.
-            - "all": all axes are labelled.
+            - "all": All axes are labelled.
+            - "keep": Do not do anything.
 
         axes_class : subclass of `matplotlib.axes.Axes`, default: None
         aspect : bool, default: False
@@ -258,13 +259,14 @@ def set_label_mode(self, mode):
 
         Parameters
         ----------
-        mode : {"L", "1", "all"}
+        mode : {"L", "1", "all", "keep"}
             The label mode:
 
             - "L": All axes on the left column get vertical tick labels;
               all axes on the bottom row get horizontal tick labels.
             - "1": Only the bottom left axes is labelled.
-            - "all": all axes are labelled.
+            - "all": All axes are labelled.
+            - "keep": Do not do anything.
         """
         if mode == "all":
             for ax in self.axes_all:
@@ -292,6 +294,16 @@ def set_label_mode(self, mode):
 
             ax = self.axes_llc
             _tick_only(ax, bottom_on=False, left_on=False)
+        else:
+            # Use _api.check_in_list at the top of the method when deprecation
+            # period expires
+            if mode != 'keep':
+                _api.warn_deprecated(
+                    '3.7', name="Grid label_mode",
+                    message='Passing a non-defined label_mode is deprecated '
+                            'since %(since)s and will become an error '
+                            '%(removal)s. To silence this warning, pass '
+                            '"keep", which gives the same behaviour.')
 
     def get_divider(self):
         return self._divider

lib/mpl_toolkits/axes_grid1/tests/test_axes_grid1.py

@@ -4,7 +4,7 @@
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import matplotlib.ticker as mticker
-from matplotlib import cbook
+from matplotlib import _api, cbook
 from matplotlib.backend_bases import MouseEvent
 from matplotlib.colors import LogNorm
 from matplotlib.transforms import Bbox, TransformedBbox
@@ -403,6 +403,15 @@ def test_image_grid_single_bottom():
     grid.cbar_axes[0].colorbar(im)
 
 
+def test_image_grid_label_mode_deprecation_warning():
+    imdata = np.arange(9).reshape((3, 3))
+
+    fig = plt.figure()
+    with pytest.warns(_api.MatplotlibDeprecationWarning,
+                      match="Passing a non-defined label_mode"):
+        grid = ImageGrid(fig, (0, 0, 1, 1), (2, 1), label_mode="foo")
+
+
 @image_comparison(['image_grid.png'],
                   remove_text=True, style='mpl20',
                   savefig_kwarg={'bbox_inches': 'tight'})