Make kwargs names in scale.py not include the axis direction.

anntzer · anntzer · commit 2c03e251bcc4 · 2020-02-09T00:51:01.000+01:00
- Make names of kwargs to Scale subclasses independent of whether the
  underlying axis is x or y (so that after the deprecation period, one
  can just have a normal signature --
  `def __init__(self, *, base=10, ...)`.

  We could possibly also change semilogx and semilogy to use the
  unsuffixed names (with deprecation), leaving only loglog with the
  suffixed names, or even also make loglog use unsuffixed names, in
  which case it would become impossible to set separate x and y bases
  directly in loglog -- one should then do `gca().set_xscale("log",
  base=...)` which doesn't seem too onerous.  (loglog is the only case
  where the suffixed names has *some* utility.)

  In general, note that having kwargs that depend on the axis direction
  doesn't really scale -- for example, if we were to finally add
  log-scale support to mplot3d, should scale.py know about it and add
  `basez`?  Should we have `baser` for log-scale polar plots? (at least
  in the radial direction, they make sense)

- Move argument validation up the the Transform subclasses.

- Make SymmetricalLogScale.{base,linthresh,linscale} properties
  mapping to the underlying transform so that they can't go out of sync.
diff --git a/doc/api/next_api_changes/deprecations.rst b/doc/api/next_api_changes/deprecations.rst
@@ -184,3 +184,13 @@ Debian 8 (2015, EOL 06/2020) and Ubuntu 14.04 (EOL 04/2019) were the
 last versions of Debian and Ubuntu to ship avconv.  It remains possible
 to force the use of avconv by using the ffmpeg-based writers with
 :rc:`animation.ffmpeg_path` set to "avconv".
+
+Signature of `.LogScale` and `.SymmetricalLogScale`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These classes used to take keyword arguments that depends on the axis
+orientation ("basex" vs "basey", "nonposx" vs "nonposy"); these parameter
+names are now deprecated in favor of "base", "nonpos", etc.  This deprecation
+also affects e.g. ``ax.set_yscale("log", basey=...)`` which must now be
+spelled ``ax.set_yscale("log", base=...)``.  The only place where "basex", etc.
+remain in use is in the helper functions `~.Axes.loglog`, `~.Axes.semilogx`,
+and `~.Axes.semilogy` (because `~.Axes.loglog` takes both "basex" and "basey").
diff --git a/examples/scales/log_demo.py b/examples/scales/log_demo.py
@@ -26,7 +26,8 @@
 ax2.grid()
 
 # log x and y axis
-ax3.loglog(t, 20 * np.exp(-t / 10.0), basex=2)
+ax3.loglog(t, 20 * np.exp(-t / 10.0))
+ax3.set_xscale('log', base=2)
 ax3.set(title='loglog base 2 on x')
 ax3.grid()
 
@@ -35,8 +36,8 @@
 x = 10.0**np.linspace(0.0, 2.0, 20)
 y = x**2.0
 
-ax4.set_xscale("log", nonposx='clip')
-ax4.set_yscale("log", nonposy='clip')
+ax4.set_xscale("log", nonpos='clip')
+ax4.set_yscale("log", nonpos='clip')
 ax4.set(title='Errorbars go negative')
 ax4.errorbar(x, y, xerr=0.1 * x, yerr=5.0 + 0.75 * y)
 # ylim must be set after errorbar to allow errorbar to autoscale limits
diff --git a/examples/scales/scales.py b/examples/scales/scales.py
@@ -45,7 +45,7 @@
 # symmetric log
 ax = axs[1, 1]
 ax.plot(x, y - y.mean())
-ax.set_yscale('symlog', linthreshy=0.02)
+ax.set_yscale('symlog', linthresh=0.02)
 ax.set_title('symlog')
 ax.grid(True)
 
diff --git a/examples/scales/symlog_demo.py b/examples/scales/symlog_demo.py
@@ -27,7 +27,7 @@
 plt.subplot(313)
 plt.plot(x, np.sin(x / 3.0))
 plt.xscale('symlog')
-plt.yscale('symlog', linthreshy=0.015)
+plt.yscale('symlog', linthresh=0.015)
 plt.grid(True)
 plt.ylabel('symlog both')
 
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1795,16 +1795,13 @@ def loglog(self, *args, **kwargs):
         **kwargs
             All parameters supported by `.plot`.
         """
-        dx = {k: kwargs.pop(k) for k in ['basex', 'subsx', 'nonposx']
+        dx = {k[:-1]: kwargs.pop(k) for k in ['basex', 'subsx', 'nonposx']
               if k in kwargs}
-        dy = {k: kwargs.pop(k) for k in ['basey', 'subsy', 'nonposy']
-              if k in kwargs}
-
         self.set_xscale('log', **dx)
+        dy = {k[:-1]: kwargs.pop(k) for k in ['basey', 'subsy', 'nonposy']
+              if k in kwargs}
         self.set_yscale('log', **dy)
-
-        l = self.plot(*args, **kwargs)
-        return l
+        return self.plot(*args, **kwargs)
 
     # @_preprocess_data() # let 'plot' do the unpacking..
     @docstring.dedent_interpd
@@ -1848,12 +1845,10 @@ def semilogx(self, *args, **kwargs):
         **kwargs
             All parameters supported by `.plot`.
         """
-        d = {k: kwargs.pop(k) for k in ['basex', 'subsx', 'nonposx']
+        d = {k[:-1]: kwargs.pop(k) for k in ['basex', 'subsx', 'nonposx']
              if k in kwargs}
-
         self.set_xscale('log', **d)
-        l = self.plot(*args, **kwargs)
-        return l
+        return self.plot(*args, **kwargs)
 
     # @_preprocess_data() # let 'plot' do the unpacking..
     @docstring.dedent_interpd
@@ -1897,12 +1892,10 @@ def semilogy(self, *args, **kwargs):
         **kwargs
             All parameters supported by `.plot`.
         """
-        d = {k: kwargs.pop(k) for k in ['basey', 'subsy', 'nonposy']
+        d = {k[:-1]: kwargs.pop(k) for k in ['basey', 'subsy', 'nonposy']
              if k in kwargs}
         self.set_yscale('log', **d)
-        l = self.plot(*args, **kwargs)
-
-        return l
+        return self.plot(*args, **kwargs)
 
     @_preprocess_data(replace_names=["x"], label_namer="x")
     def acorr(self, x, **kwargs):
@@ -2343,11 +2336,11 @@ def bar(self, x, height, width=0.8, bottom=None, *, align="center",
         if orientation == 'vertical':
             self._process_unit_info(xdata=x, ydata=height, kwargs=kwargs)
             if log:
-                self.set_yscale('log', nonposy='clip')
+                self.set_yscale('log', nonpos='clip')
         elif orientation == 'horizontal':
             self._process_unit_info(xdata=width, ydata=y, kwargs=kwargs)
             if log:
-                self.set_xscale('log', nonposx='clip')
+                self.set_xscale('log', nonpos='clip')
 
         # lets do some conversions now since some types cannot be
         # subtracted uniformly
@@ -6715,9 +6708,9 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
 
             if log:
                 if orientation == 'horizontal':
-                    self.set_xscale('log', nonposx='clip')
+                    self.set_xscale('log', nonpos='clip')
                 else:  # orientation == 'vertical'
-                    self.set_yscale('log', nonposy='clip')
+                    self.set_yscale('log', nonpos='clip')
 
             if align == 'left':
                 x -= 0.5*(bins[1]-bins[0])
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
@@ -281,8 +281,11 @@ class LogTransform(Transform):
 
     def __init__(self, base, nonpos='clip'):
         Transform.__init__(self)
+        if base <= 0 or base == 1:
+            raise ValueError('The log base cannot be <= 0 or == 1')
         self.base = base
-        self._clip = {"clip": True, "mask": False}[nonpos]
+        self._clip = cbook._check_getitem(
+            {"clip": True, "mask": False}, nonpos=nonpos)
 
     def __str__(self):
         return "{}(base={}, nonpos={!r})".format(
@@ -362,41 +365,32 @@ def __init__(self, axis, **kwargs):
         ----------
         axis : `~matplotlib.axis.Axis`
             The axis for the scale.
-        basex, basey : float, default: 10
+        base : float, default: 10
             The base of the logarithm.
-        nonposx, nonposy : {'clip', 'mask'}, default: 'clip'
+        nonpos : {'clip', 'mask'}, default: 'clip'
             Determines the behavior for non-positive values. They can either
             be masked as invalid, or clipped to a very small positive number.
-        subsx, subsy : sequence of int, default: None
-            Where to place the subticks between each major tick.
-            For example, in a log10 scale: ``[2, 3, 4, 5, 6, 7, 8, 9]``
-            will place 8 logarithmically spaced minor ticks between
-            each major tick.
+        subs : sequence of int, default: None
+            Where to place the subticks between each major tick.  For example,
+            in a log10 scale, ``[2, 3, 4, 5, 6, 7, 8, 9]`` will place 8
+            logarithmically spaced minor ticks between each major tick.
         """
-        if axis.axis_name == 'x':
-            base = kwargs.pop('basex', 10.0)
-            subs = kwargs.pop('subsx', None)
-            nonpos = kwargs.pop('nonposx', 'clip')
-            cbook._check_in_list(['mask', 'clip'], nonposx=nonpos)
-        else:
-            base = kwargs.pop('basey', 10.0)
-            subs = kwargs.pop('subsy', None)
-            nonpos = kwargs.pop('nonposy', 'clip')
-            cbook._check_in_list(['mask', 'clip'], nonposy=nonpos)
-
-        if kwargs:
-            raise TypeError(f"LogScale got an unexpected keyword "
-                            f"argument {next(iter(kwargs))!r}")
-
-        if base <= 0 or base == 1:
-            raise ValueError('The log base cannot be <= 0 or == 1')
-
+        # After the deprecation, the whole (outer) __init__ can be replaced by
+        # def __init__(self, axis, *, base=10, subs=None, nonpos="clip"): ...
+        # The following is to emit the right warnings depending on the axis
+        # used, as the *old* kwarg names depended on the axis.
+        axis_name = getattr(axis, "axis_name", "x")
+        @cbook._rename_parameter("3.3", f"base{axis_name}", "base")
+        @cbook._rename_parameter("3.3", f"subs{axis_name}", "subs")
+        @cbook._rename_parameter("3.3", f"nonpos{axis_name}", "nonpos")
+        def __init__(*, base=10, subs=None, nonpos="clip"):
+            return base, subs, nonpos
+
+        base, subs, nonpos = __init__(**kwargs)
         self._transform = LogTransform(base, nonpos)
         self.subs = subs
 
-    @property
-    def base(self):
-        return self._transform.base
+    base = property(lambda self: self._transform.base)
 
     def set_default_locators_and_formatters(self, axis):
         # docstring inherited
@@ -463,6 +457,12 @@ class SymmetricalLogTransform(Transform):
 
     def __init__(self, base, linthresh, linscale):
         Transform.__init__(self)
+        if base <= 1.0:
+            raise ValueError("'base' must be larger than 1")
+        if linthresh <= 0.0:
+            raise ValueError("'linthresh' must be positive")
+        if linscale <= 0.0:
+            raise ValueError("'linscale' must be positive")
         self.base = base
         self.linthresh = linthresh
         self.linscale = linscale
@@ -523,19 +523,19 @@ class SymmetricalLogScale(ScaleBase):
 
     Parameters
     ----------
-    basex, basey : float, default: 10
+    base : float, default: 10
         The base of the logarithm.
 
-    linthreshx, linthreshy : float, default: 2
+    linthresh : float, default: 2
         Defines the range ``(-x, x)``, within which the plot is linear.
         This avoids having the plot go to infinity around zero.
 
-    subsx, subsy : sequence of int
+    subs : sequence of int
         Where to place the subticks between each major tick.
         For example, in a log10 scale: ``[2, 3, 4, 5, 6, 7, 8, 9]`` will place
         8 logarithmically spaced minor ticks between each major tick.
 
-    linscalex, linscaley : float, optional
+    linscale : float, optional
         This allows the linear range ``(-linthresh, linthresh)`` to be
         stretched relative to the logarithmic range. Its value is the number of
         decades to use for each half of the linear range. For example, when
@@ -557,40 +557,31 @@ def InvertedSymmetricalLogTransform(self):
         return InvertedSymmetricalLogTransform
 
     def __init__(self, axis, **kwargs):
-        if axis.axis_name == 'x':
-            base = kwargs.pop('basex', 10.0)
-            linthresh = kwargs.pop('linthreshx', 2.0)
-            subs = kwargs.pop('subsx', None)
-            linscale = kwargs.pop('linscalex', 1.0)
-        else:
-            base = kwargs.pop('basey', 10.0)
-            linthresh = kwargs.pop('linthreshy', 2.0)
-            subs = kwargs.pop('subsy', None)
-            linscale = kwargs.pop('linscaley', 1.0)
-        if kwargs:
-            warn_deprecated(
-                '3.2.0',
-                message=(
-                    f"SymmetricalLogScale got an unexpected keyword "
-                    f"argument {next(iter(kwargs))!r}. "
-                    'In the future this will raise TypeError')
-            )
-            # raise TypeError(f"SymmetricalLogScale got an unexpected keyword "
-            #                 f"argument {next(iter(kwargs))!r}")
-
-        if base <= 1.0:
-            raise ValueError("'basex/basey' must be larger than 1")
-        if linthresh <= 0.0:
-            raise ValueError("'linthreshx/linthreshy' must be positive")
-        if linscale <= 0.0:
-            raise ValueError("'linscalex/linthreshy' must be positive")
-
+        axis_name = getattr(axis, "axis_name", "x")
+        # See explanation in LogScale.__init__.
+        @cbook._rename_parameter("3.3", f"base{axis_name}", "base")
+        @cbook._rename_parameter("3.3", f"linthresh{axis_name}", "linthresh")
+        @cbook._rename_parameter("3.3", f"subs{axis_name}", "subs")
+        @cbook._rename_parameter("3.3", f"linscale{axis_name}", "linscale")
+        def __init__(*, base=10, linthresh=2, subs=None, linscale=1, **kwargs):
+            if kwargs:
+                warn_deprecated(
+                    "3.2.0",
+                    message=(
+                        f"SymmetricalLogScale got an unexpected keyword "
+                        f"argument {next(iter(kwargs))!r}; in the future, "
+                        f"this will raise a TypeError")
+                )
+            return base, linthresh, subs, linscale
+
+        base, linthresh, subs, linscale = __init__(**kwargs)
         self._transform = SymmetricalLogTransform(base, linthresh, linscale)
-        self.base = base
-        self.linthresh = linthresh
-        self.linscale = linscale
         self.subs = subs
 
+    base = property(lambda self: self._transform.base)
+    linthresh = property(lambda self: self._transform.linthresh)
+    linscale = property(lambda self: self._transform.linscale)
+
     def set_default_locators_and_formatters(self, axis):
         # docstring inherited
         axis.set_major_locator(SymmetricalLogLocator(self.get_transform()))
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -1150,9 +1150,9 @@ def test_symlog2():
     x = np.arange(-50, 50, 0.001)
 
     fig, axs = plt.subplots(5, 1)
-    for ax, linthreshx in zip(axs, [20., 2., 1., 0.1, 0.01]):
+    for ax, linthresh in zip(axs, [20., 2., 1., 0.1, 0.01]):
         ax.plot(x, x)
-        ax.set_xscale('symlog', linthreshx=linthreshx)
+        ax.set_xscale('symlog', linthresh=linthresh)
         ax.grid(True)
     axs[-1].set_ylim(-0.1, 0.1)
 
@@ -2241,9 +2241,9 @@ def test_log_scales():
     fig = plt.figure()
     ax = fig.add_subplot(1, 1, 1)
     ax.plot(np.log(np.linspace(0.1, 100)))
-    ax.set_yscale('log', basey=5.5)
+    ax.set_yscale('log', base=5.5)
     ax.invert_yaxis()
-    ax.set_xscale('log', basex=9.0)
+    ax.set_xscale('log', base=9.0)
 
 
 def test_log_scales_no_data():
diff --git a/lib/matplotlib/tests/test_scale.py b/lib/matplotlib/tests/test_scale.py
@@ -88,7 +88,7 @@ def test_log_scatter():
 
 def test_logscale_subs():
     fig, ax = plt.subplots()
-    ax.set_yscale('log', subsy=np.array([2, 3, 4]))
+    ax.set_yscale('log', subs=np.array([2, 3, 4]))
     # force draw
     fig.canvas.draw()
 
@@ -108,16 +108,14 @@ def test_logscale_mask():
 def test_extra_kwargs_raise_or_warn():
     fig, ax = plt.subplots()
 
-    # with pytest.raises(TypeError):
     with pytest.warns(MatplotlibDeprecationWarning):
-        ax.set_yscale('linear', nonpos='mask')
+        ax.set_yscale('linear', foo='mask')
 
     with pytest.raises(TypeError):
-        ax.set_yscale('log', nonpos='mask')
+        ax.set_yscale('log', foo='mask')
 
-    # with pytest.raises(TypeError):
     with pytest.warns(MatplotlibDeprecationWarning):
-        ax.set_yscale('symlog', nonpos='mask')
+        ax.set_yscale('symlog', foo='mask')
 
 
 def test_logscale_invert_transform():
@@ -150,7 +148,7 @@ def test_logscale_nonpos_values():
     ax1.hist(xs, range=(-5, 5), bins=10)
     ax1.set_yscale('log')
     ax2.hist(xs, range=(-5, 5), bins=10)
-    ax2.set_yscale('log', nonposy='mask')
+    ax2.set_yscale('log', nonpos='mask')
 
     xdata = np.arange(0, 10, 0.01)
     ydata = np.exp(-xdata)
diff --git a/tutorials/introductory/pyplot.py b/tutorials/introductory/pyplot.py
@@ -443,7 +443,7 @@ def f(t):
 # symmetric log
 plt.subplot(223)
 plt.plot(x, y - y.mean())
-plt.yscale('symlog', linthreshy=0.01)
+plt.yscale('symlog', linthresh=0.01)
 plt.title('symlog')
 plt.grid(True)
 
