Merge pull request #11137 from Zac-HD/issue-9912-cleanup

timhoffm · web-flow · commit 4a12a604895e · 2018-05-08T08:11:43.000+02:00
Convert **kwargs to named arguments for a clearer API
diff --git a/doc/api/next_api_changes/2018-04-22-ZHD.rst b/doc/api/next_api_changes/2018-04-22-ZHD.rst
@@ -0,0 +1,14 @@
+Different exception types for undocumented options
+--------------------------------------------------
+
+- Passing ``style='comma'`` to :meth:`~matplotlib.axes.Axes.ticklabel_format`
+  was never supported.  It now raises ``ValueError`` like all other
+  unsupported styles, rather than ``NotImplementedError``.
+
+- Passing the undocumented ``xmin`` or ``xmax`` arguments to
+  :meth:`~matplotlib.axes.Axes.set_xlim` would silently override the ``left``
+  and ``right`` arguments.  :meth:`~matplotlib.axes.Axes.set_ylim` and the
+  3D equivalents (e.g. :meth:`~mpl_toolkits.axes.Axes3D.set_zlim3d`) had a
+  corresponding problem.
+  The ``_min`` and ``_max`` arguments are now deprecated, and a ``TypeError``
+  will be raised if they would override the earlier limit arguments.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2756,8 +2756,6 @@ def ticklabel_format(self, *, axis='both', style='', scilimits=None,
             sb = True
         elif style == 'plain':
             sb = False
-        elif style == 'comma':
-            raise NotImplementedError("comma style remains to be added")
         elif style == '':
             sb = None
         else:
@@ -3028,7 +3026,8 @@ def _validate_converted_limits(self, limit, convert):
                 raise ValueError("Axis limits cannot be NaN or Inf")
             return converted_limit
 
-    def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw):
+    def set_xlim(self, left=None, right=None, emit=True, auto=False,
+                 *, xmin=None, xmax=None):
         """
         Set the data limits for the x-axis
 
@@ -3039,6 +3038,9 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw):
         left : scalar, optional
             The left xlim (default: None, which leaves the left limit
             unchanged).
+            The left and right xlims may be passed as the tuple
+            (`left`, `right`) as the first positional argument (or as
+            the `left` keyword argument).
 
         right : scalar, optional
             The right xlim (default: None, which leaves the right limit
@@ -3051,10 +3053,11 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw):
             Whether to turn on autoscaling of the x-axis. True turns on,
             False turns off (default action), None leaves unchanged.
 
-        xlimits : tuple, optional
-            The left and right xlims may be passed as the tuple
-            (`left`, `right`) as the first positional argument (or as
-            the `left` keyword argument).
+        xmin, xmax : scalar, optional
+            These arguments are deprecated and will be removed in a future
+            version.  They are equivalent to left and right respectively,
+            and it is an error to pass both `xmin` and `left` or
+            `xmax` and `right`.
 
         Returns
         -------
@@ -3085,15 +3088,20 @@ def set_xlim(self, left=None, right=None, emit=True, auto=False, **kw):
         >>> set_xlim(5000, 0)
 
         """
-        if 'xmin' in kw:
-            left = kw.pop('xmin')
-        if 'xmax' in kw:
-            right = kw.pop('xmax')
-        if kw:
-            raise ValueError("unrecognized kwargs: %s" % list(kw))
-
         if right is None and iterable(left):
             left, right = left
+        if xmin is not None:
+            cbook.warn_deprecated('3.0', name='`xmin`',
+                                  alternative='`left`', obj_type='argument')
+            if left is not None:
+                raise TypeError('Cannot pass both `xmin` and `left`')
+            left = xmin
+        if xmax is not None:
+            cbook.warn_deprecated('3.0', name='`xmax`',
+                                  alternative='`right`', obj_type='argument')
+            if right is not None:
+                raise TypeError('Cannot pass both `xmax` and `right`')
+            right = xmax
 
         self._process_unit_info(xdata=(left, right))
         left = self._validate_converted_limits(left, self.convert_xunits)
@@ -3358,7 +3366,8 @@ def get_ylim(self):
         """
         return tuple(self.viewLim.intervaly)
 
-    def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw):
+    def set_ylim(self, bottom=None, top=None, emit=True, auto=False,
+                 *, ymin=None, ymax=None):
         """
         Set the data limits for the y-axis
 
@@ -3369,6 +3378,9 @@ def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw):
         bottom : scalar, optional
             The bottom ylim (default: None, which leaves the bottom
             limit unchanged).
+            The bottom and top ylims may be passed as the tuple
+            (`bottom`, `top`) as the first positional argument (or as
+            the `bottom` keyword argument).
 
         top : scalar, optional
             The top ylim (default: None, which leaves the top limit
@@ -3381,10 +3393,11 @@ def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw):
             Whether to turn on autoscaling of the y-axis. True turns on,
             False turns off (default action), None leaves unchanged.
 
-        ylimits : tuple, optional
-            The bottom and top yxlims may be passed as the tuple
-            (`bottom`, `top`) as the first positional argument (or as
-            the `bottom` keyword argument).
+        ymin, ymax : scalar, optional
+            These arguments are deprecated and will be removed in a future
+            version.  They are equivalent to bottom and top respectively,
+            and it is an error to pass both `xmin` and `bottom` or
+            `xmax` and `top`.
 
         Returns
         -------
@@ -3414,15 +3427,20 @@ def set_ylim(self, bottom=None, top=None, emit=True, auto=False, **kw):
 
         >>> set_ylim(5000, 0)
         """
-        if 'ymin' in kw:
-            bottom = kw.pop('ymin')
-        if 'ymax' in kw:
-            top = kw.pop('ymax')
-        if kw:
-            raise ValueError("unrecognized kwargs: %s" % list(kw))
-
         if top is None and iterable(bottom):
             bottom, top = bottom
+        if ymin is not None:
+            cbook.warn_deprecated('3.0', name='`ymin`',
+                                  alternative='`bottom`', obj_type='argument')
+            if bottom is not None:
+                raise TypeError('Cannot pass both `ymin` and `bottom`')
+            bottom = ymin
+        if ymax is not None:
+            cbook.warn_deprecated('3.0', name='`ymax`',
+                                  alternative='`top`', obj_type='argument')
+            if top is not None:
+                raise TypeError('Cannot pass both `ymax` and `top`')
+            top = ymax
 
         bottom = self._validate_converted_limits(bottom, self.convert_yunits)
         top = self._validate_converted_limits(top, self.convert_yunits)
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -334,12 +334,10 @@ def get_view_interval(self):
         raise NotImplementedError('Derived must override')
 
     def _apply_params(self, **kw):
-        switchkw = ['gridOn', 'tick1On', 'tick2On', 'label1On', 'label2On']
-        switches = [k for k in kw if k in switchkw]
-        for k in switches:
-            setattr(self, k, kw.pop(k))
-        newmarker = [k for k in kw if k in ['size', 'width', 'pad', 'tickdir']]
-        if newmarker:
+        for name in ['gridOn', 'tick1On', 'tick2On', 'label1On', 'label2On']:
+            if name in kw:
+                setattr(self, name, kw.pop(name))
+        if any(k in kw for k in ['size', 'width', 'pad', 'tickdir']):
             self._size = kw.pop('size', self._size)
             # Width could be handled outside this block, but it is
             # convenient to leave it here.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1365,19 +1365,19 @@ def ylim(*args, **kwargs):
     return ret
 
 
-def xticks(*args, **kwargs):
+def xticks(ticks=None, labels=None, **kwargs):
     """
     Get or set the current tick locations and labels of the x-axis.
 
     Call signatures::
 
         locs, labels = xticks()           # Get locations and labels
 
-        xticks(locs, [labels], **kwargs)  # Set locations and labels
+        xticks(ticks, [labels], **kwargs)  # Set locations and labels
 
     Parameters
     ----------
-    locs : array_like
+    ticks : array_like
         A list of positions at which ticks should be placed. You can pass an
         empty list to disable xticks.
 
@@ -1427,36 +1427,34 @@ def xticks(*args, **kwargs):
     """
     ax = gca()
 
-    if len(args) == 0:
+    if ticks is None and labels is None:
         locs = ax.get_xticks()
         labels = ax.get_xticklabels()
-    elif len(args) == 1:
-        locs = ax.set_xticks(args[0])
+    elif labels is None:
+        locs = ax.set_xticks(ticks)
         labels = ax.get_xticklabels()
-    elif len(args) == 2:
-        locs = ax.set_xticks(args[0])
-        labels = ax.set_xticklabels(args[1], **kwargs)
     else:
-        raise TypeError('Illegal number of arguments to xticks')
+        locs = ax.set_xticks(ticks)
+        labels = ax.set_xticklabels(labels, **kwargs)
     for l in labels:
         l.update(kwargs)
 
     return locs, silent_list('Text xticklabel', labels)
 
 
-def yticks(*args, **kwargs):
+def yticks(ticks=None, labels=None, **kwargs):
     """
     Get or set the current tick locations and labels of the y-axis.
 
     Call signatures::
 
         locs, labels = yticks()           # Get locations and labels
 
-        yticks(locs, [labels], **kwargs)  # Set locations and labels
+        yticks(ticks, [labels], **kwargs)  # Set locations and labels
 
     Parameters
     ----------
-    locs : array_like
+    ticks : array_like
         A list of positions at which ticks should be placed. You can pass an
         empty list to disable yticks.
 
@@ -1506,17 +1504,15 @@ def yticks(*args, **kwargs):
     """
     ax = gca()
 
-    if len(args) == 0:
+    if ticks is None and labels is None:
         locs = ax.get_yticks()
         labels = ax.get_yticklabels()
-    elif len(args) == 1:
-        locs = ax.set_yticks(args[0])
+    elif labels is None:
+        locs = ax.set_yticks(ticks)
         labels = ax.get_yticklabels()
-    elif len(args) == 2:
-        locs = ax.set_yticks(args[0])
-        labels = ax.set_yticklabels(args[1], **kwargs)
     else:
-        raise TypeError('Illegal number of arguments to yticks')
+        locs = ax.set_yticks(ticks)
+        labels = ax.set_yticklabels(labels, **kwargs)
     for l in labels:
         l.update(kwargs)
 
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
