From 4e2d5f4bebc5b67b2d9680d377e3d72aa11b10e1 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Thu, 6 May 2021 20:26:34 +0200 Subject: [PATCH] Rename (with deprecation) first parameter of grid() from b to visible. 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. --- .../deprecations/20173-AL.rst | 4 ++ lib/matplotlib/axes/_base.py | 15 +++---- lib/matplotlib/axis.py | 41 ++++++------------- lib/matplotlib/pyplot.py | 4 +- lib/mpl_toolkits/axisartist/axislines.py | 17 ++++---- lib/mpl_toolkits/mplot3d/axes3d.py | 7 ++-- 6 files changed, 40 insertions(+), 48 deletions(-) create mode 100644 doc/api/next_api_changes/deprecations/20173-AL.rst diff --git a/doc/api/next_api_changes/deprecations/20173-AL.rst b/doc/api/next_api_changes/deprecations/20173-AL.rst new file mode 100644 index 000000000000..d9bce337af9f --- /dev/null +++ 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 index f72e2950100f..7bcdb6ddba0b 100644 --- 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 index d1b7c2413ed4..bd52d28d2eae 100644 --- 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 index fcee92477870..8b5cad11c592 100644 --- 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 index c49610b93831..65c506341a2c 100644 --- 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 index ed97b9658560..ddb3c88b5d7f 100644 --- 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):