Rename (with deprecation) first parameter of grid() from b to visible.

anntzer · anntzer · commit 4e2d5f4bebc5 · 2021-05-20T23:42:46.000+02:00
This simplifies the implementation of Axis.grid, which previously had to
handle either of the names being input.  It's not as if "b" was a
particularly meaningful name, either.
diff --git a/doc/api/next_api_changes/deprecations/20173-AL.rst b/doc/api/next_api_changes/deprecations/20173-AL.rst
@@ -0,0 +1,4 @@
+The first parameter of ``Axes.grid`` and ``Axis.grid`` has been renamed to *visible*
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The parameter was previously named *b*.  This deprecation only matters if
+that parameter was passed using a keyword argument, e.g. ``grid(b=False)``.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -3191,17 +3191,18 @@ def set_axisbelow(self, b):
         self.stale = True
 
     @docstring.dedent_interpd
-    def grid(self, b=None, which='major', axis='both', **kwargs):
+    @_api.rename_parameter("3.5", "b", "visible")
+    def grid(self, visible=None, which='major', axis='both', **kwargs):
         """
         Configure the grid lines.
 
         Parameters
         ----------
-        b : bool or None, optional
-            Whether to show the grid lines. If any *kwargs* are supplied,
-            it is assumed you want the grid on and *b* will be set to True.
+        visible : bool or None, optional
+            Whether to show the grid lines.  If any *kwargs* are supplied, it
+            is assumed you want the grid on and *visible* will be set to True.
 
-            If *b* is *None* and there are no *kwargs*, this toggles the
+            If *visible* is *None* and there are no *kwargs*, this toggles the
             visibility of the lines.
 
         which : {'major', 'minor', 'both'}, optional
@@ -3229,9 +3230,9 @@ def grid(self, b=None, which='major', axis='both', **kwargs):
         """
         _api.check_in_list(['x', 'y', 'both'], axis=axis)
         if axis in ['x', 'both']:
-            self.xaxis.grid(b, which=which, **kwargs)
+            self.xaxis.grid(visible, which=which, **kwargs)
         if axis in ['y', 'both']:
-            self.yaxis.grid(b, which=which, **kwargs)
+            self.yaxis.grid(visible, which=which, **kwargs)
 
     def ticklabel_format(self, *, axis='both', style='', scilimits=None,
                          useOffset=None, useLocale=None, useMathText=None):
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -1398,17 +1398,18 @@ def get_minor_ticks(self, numticks=None):
 
         return self.minorTicks[:numticks]
 
-    def grid(self, b=None, which='major', **kwargs):
+    @_api.rename_parameter("3.5", "b", "visible")
+    def grid(self, visible=None, which='major', **kwargs):
         """
         Configure the grid lines.
 
         Parameters
         ----------
-        b : bool or None
-            Whether to show the grid lines. If any *kwargs* are supplied,
-            it is assumed you want the grid on and *b* will be set to True.
+        visible : bool or None
+            Whether to show the grid lines.  If any *kwargs* are supplied, it
+            is assumed you want the grid on and *visible* will be set to True.
 
-            If *b* is *None* and there are no *kwargs*, this toggles the
+            If *visible* is *None* and there are no *kwargs*, this toggles the
             visibility of the lines.
 
         which : {'major', 'minor', 'both'}
@@ -1419,40 +1420,24 @@ def grid(self, b=None, which='major', **kwargs):
 
                 grid(color='r', linestyle='-', linewidth=2)
         """
-        TOGGLE = object()
-        UNSET = object()
-        visible = kwargs.pop('visible', UNSET)
-
-        if b is None:
-            if visible is UNSET:
-                if kwargs:  # grid(color='r')
-                    b = True
-                else:  # grid()
-                    b = TOGGLE
-            else:  # grid(visible=v)
-                b = visible
-        else:
-            if visible is not UNSET and bool(b) != bool(visible):
-                # grid(True, visible=False), grid(False, visible=True)
-                raise ValueError(
-                    "'b' and 'visible' specify inconsistent grid visibilities")
-            if kwargs and not b:  # something false-like but not None
-                # grid(0, visible=True)
+        if kwargs:
+            if visible is None:
+                visible = True
+            elif not visible:  # something false-like but not None
                 _api.warn_external('First parameter to grid() is false, '
                                    'but line properties are supplied. The '
                                    'grid will be enabled.')
-                b = True
-
+                visible = True
         which = which.lower()
         _api.check_in_list(['major', 'minor', 'both'], which=which)
         gridkw = {'grid_' + item[0]: item[1] for item in kwargs.items()}
         if which in ['minor', 'both']:
             gridkw['gridOn'] = (not self._minor_tick_kw['gridOn']
-                                if b is TOGGLE else b)
+                                if visible is None else visible)
             self.set_tick_params(which='minor', **gridkw)
         if which in ['major', 'both']:
             gridkw['gridOn'] = (not self._major_tick_kw['gridOn']
-                                if b is TOGGLE else b)
+                                if visible is None else visible)
             self.set_tick_params(which='major', **gridkw)
         self.stale = True
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2813,8 +2813,8 @@ def fill_betweenx(
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
 @_copy_docstring_and_deprecators(Axes.grid)
-def grid(b=None, which='major', axis='both', **kwargs):
-    return gca().grid(b=b, which=which, axis=axis, **kwargs)
+def grid(visible=None, which='major', axis='both', **kwargs):
+    return gca().grid(visible=visible, which=which, axis=axis, **kwargs)
 
 
 # Autogenerated by boilerplate.py.  Do not edit as changes will be lost.
diff --git a/lib/mpl_toolkits/axisartist/axislines.py b/lib/mpl_toolkits/axisartist/axislines.py
@@ -528,22 +528,23 @@ def cla(self):
     def get_grid_helper(self):
         return self._grid_helper
 
-    def grid(self, b=None, which='major', axis="both", **kwargs):
+    @_api.rename_parameter("3.5", "b", "visible")
+    def grid(self, visible=None, which='major', axis="both", **kwargs):
         """
         Toggle the gridlines, and optionally set the properties of the lines.
         """
         # There are some discrepancies in the behavior of grid() between
         # axes_grid and Matplotlib, because axes_grid explicitly sets the
         # visibility of the gridlines.
-        super().grid(b, which=which, axis=axis, **kwargs)
+        super().grid(visible, which=which, axis=axis, **kwargs)
         if not self._axisline_on:
             return
-        if b is None:
-            b = (self.axes.xaxis._minor_tick_kw["gridOn"]
-                 or self.axes.xaxis._major_tick_kw["gridOn"]
-                 or self.axes.yaxis._minor_tick_kw["gridOn"]
-                 or self.axes.yaxis._major_tick_kw["gridOn"])
-        self.gridlines.set(which=which, axis=axis, visible=b)
+        if visible is None:
+            visible = (self.axes.xaxis._minor_tick_kw["gridOn"]
+                       or self.axes.xaxis._major_tick_kw["gridOn"]
+                       or self.axes.yaxis._minor_tick_kw["gridOn"]
+                       or self.axes.yaxis._major_tick_kw["gridOn"])
+        self.gridlines.set(which=which, axis=axis, visible=visible)
         self.gridlines.set(**kwargs)
 
     def get_children(self):
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1371,7 +1371,8 @@ def set_frame_on(self, b):
         self._frameon = bool(b)
         self.stale = True
 
-    def grid(self, b=True, **kwargs):
+    @_api.rename_parameter("3.5", "b", "visible")
+    def grid(self, visible=True, **kwargs):
         """
         Set / unset 3D grid.
 
@@ -1383,8 +1384,8 @@ def grid(self, b=True, **kwargs):
         """
         # TODO: Operate on each axes separately
         if len(kwargs):
-            b = True
-        self._draw_grid = b
+            visible = True
+        self._draw_grid = visible
         self.stale = True
 
     def locator_params(self, axis='both', tight=None, **kwargs):
