Explicit args and refactor Axes.margins

Zac-HD · Zac-HD · commit da5f85b78203 · 2018-04-30T22:48:02.000+10:00
diff --git a/doc/api/next_api_changes/2018-04-29-ZHD.rst b/doc/api/next_api_changes/2018-04-29-ZHD.rst
@@ -0,0 +1,14 @@
+Explicit arguments instead of \*args, \*\*kwargs
+------------------------------------------------
+
+:PEP:`3102` describes keyword-only arguments, which allow Matplotlib
+to provide explicit call signatures - where we previously used
+``*args, **kwargs`` and ``kwargs.pop``, we can now expose named
+arguments.  In some places, unknown kwargs were previously ignored but
+now raise ``TypeError`` because ``**kwargs`` has been removed.
+
+- :meth:`matplotlib.axes.Axes.margins` and
+  :meth:`mpl_toolkits.mplot3d.Axes3D.margins` no longer accept
+  arbitrary keywords.  ``x``, ``y``, and (for Axes3D) ``z`` may
+  be passed as either keyword or positional arguments with the
+  same behaviour as before.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -2229,7 +2229,7 @@ def set_ymargin(self, m):
         self._ymargin = m
         self.stale = True
 
-    def margins(self, *args, **kw):
+    def margins(self, x_or_both=None, y=None, *, x=None, tight=True):
         """
         Set or retrieve autoscaling margins.
 
@@ -2267,27 +2267,26 @@ def margins(self, *args, **kw):
         it is used in autoscaling.
 
         """
-        if not args and not kw:
+        if x_or_both is not None:
+            if x is not None:
+                warnings.warn('x_or_both=%r overrides x=%r' % (x_or_both, x))
+            x = x_or_both
+        if x_or_both is not None and y is None:
+            y = x_or_both
+
+        if x is None and y is None:
+            if tight is not True:
+                warnings.warn('ignoring tight=%r in get mode' % (tight,))
             return self._xmargin, self._ymargin
 
-        tight = kw.pop('tight', True)
-        mx = kw.pop('x', None)
-        my = kw.pop('y', None)
-        if len(args) == 1:
-            mx = my = args[0]
-        elif len(args) == 2:
-            mx, my = args
-        elif len(args) > 2:
-            raise ValueError("more than two arguments were supplied")
-        if mx is not None:
-            self.set_xmargin(mx)
-        if my is not None:
-            self.set_ymargin(my)
-
-        scalex = (mx is not None)
-        scaley = (my is not None)
+        if x is not None:
+            self.set_xmargin(x)
+        if y is not None:
+            self.set_ymargin(y)
 
-        self.autoscale_view(tight=tight, scalex=scalex, scaley=scaley)
+        self.autoscale_view(
+            tight=tight, scalex=(x is not None), scaley=(y is not None)
+        )
 
     def set_rasterization_zorder(self, z):
         """
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -384,7 +384,7 @@ def set_zmargin(self, m):
         self._zmargin = m
         self.stale = True
 
-    def margins(self, *args, **kw):
+    def margins(self, x_or_both=None, y=None, z=None, *, x=None, tight=True):
         """
         Convenience method to set or retrieve autoscaling margins.
 
@@ -420,41 +420,31 @@ def margins(self, *args, **kw):
         .. versionadded :: 1.1.0
             This function was added, but not tested. Please report any bugs.
         """
-        if not args and not kw:
+        if x_or_both is not None:
+            if x is not None:
+                warnings.warn('x_or_both=%r overrides x=%r' % (x_or_both, x))
+            x = x_or_both
+        if y is None:
+            y = x_or_both
+        if z is None:
+            z = x_or_both
+
+        if x is None and y is None and z is None:
+            if tight is not True:
+                warnings.warn('ignoring tight=%r in get mode' % (tight,))
             return self._xmargin, self._ymargin, self._zmargin
 
-        tight = kw.pop('tight', True)
-        mx = kw.pop('x', None)
-        my = kw.pop('y', None)
-        mz = kw.pop('z', None)
-        if not args:
-            pass
-        elif len(args) == 1:
-            mx = my = mz = args[0]
-        elif len(args) == 2:
-            warnings.warn(
-                "Passing exactly two positional arguments to Axes3D.margins "
-                "is deprecated.  If needed, pass them as keyword arguments "
-                "instead", cbook.mplDeprecation)
-            mx, my = args
-        elif len(args) == 3:
-            mx, my, mz = args
-        else:
-            raise ValueError(
-                "Axes3D.margins takes at most three positional arguments")
-        if mx is not None:
-            self.set_xmargin(mx)
-        if my is not None:
-            self.set_ymargin(my)
-        if mz is not None:
-            self.set_zmargin(mz)
-
-        scalex = mx is not None
-        scaley = my is not None
-        scalez = mz is not None
+        if x is not None:
+            self.set_xmargin(x)
+        if y is not None:
+            self.set_ymargin(y)
+        if z is not None:
+            self.set_zmargin(z)
 
-        self.autoscale_view(tight=tight, scalex=scalex, scaley=scaley,
-                                         scalez=scalez)
+        self.autoscale_view(
+            tight=tight, scalex=(x is not None), scaley=(y is not None),
+            scalez=(z is not None)
+        )
 
     def autoscale(self, enable=True, axis='both', tight=None):
         """
