Make QuadMesh arguments with defaults keyword_only

timhoffm · timhoffm · commit 8ff9ac3f0d5a · 2021-05-23T02:54:03.000+02:00
diff --git a/doc/api/next_api_changes/deprecations/20237-TH.rst b/doc/api/next_api_changes/deprecations/20237-TH.rst
@@ -0,0 +1,4 @@
+QuadMesh keyword only parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``QuadMesh`` parameters ``antialiased`` and ``shading`` will become
+keyword-only in a future version.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -6164,16 +6164,12 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         X, Y, C, shading = self._pcolorargs('pcolormesh', *args,
                                             shading=shading, kwargs=kwargs)
-        Ny, Nx = X.shape
-        X = X.ravel()
-        Y = Y.ravel()
-
-        # convert to one dimensional arrays
+        coords = np.stack([X, Y], axis=-1)
+        # convert to one dimensional array
         C = C.ravel()
-        coords = np.column_stack((X, Y)).astype(float, copy=False)
-        collection = mcoll.QuadMesh(Nx - 1, Ny - 1, coords,
-                                    antialiased=antialiased, shading=shading,
-                                    **kwargs)
+
+        collection = mcoll.QuadMesh(
+            coords, antialiased=antialiased, shading=shading, **kwargs)
         snap = kwargs.get('snap', rcParams['pcolormesh.snap'])
         collection.set_snap(snap)
         collection.set_alpha(alpha)
@@ -6184,6 +6180,8 @@ def pcolormesh(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
 
         self.grid(False)
 
+        coords = coords.reshape(-1, 2)  # flatten the grid structure; keep x, y
+
         # Transform from native to data coordinates?
         t = collection._transform
         if (not isinstance(t, mtransforms.Transform) and
@@ -6360,7 +6358,7 @@ def pcolorfast(self, *args, alpha=None, norm=None, cmap=None, vmin=None,
             else:
                 raise ValueError("C must be 2D or 3D")
             collection = mcoll.QuadMesh(
-                nc, nr, coords, **qm_kwargs,
+                coords, **qm_kwargs,
                 alpha=alpha, cmap=cmap, norm=norm,
                 antialiased=False, edgecolors="none")
             self.add_collection(collection, autolim=False)
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -9,15 +9,17 @@
 line segments).
 """
 
+import inspect
 import math
 from numbers import Number
+import warnings
+
 import numpy as np
 
 import matplotlib as mpl
 from . import (_api, _path, artist, cbook, cm, colors as mcolors, docstring,
                hatch as mhatch, lines as mlines, path as mpath, transforms)
 from ._enums import JoinStyle, CapStyle
-import warnings
 
 
 # "color" is excluded; it is a compound setter, and its docstring differs
@@ -1991,21 +1993,73 @@ class QuadMesh(Collection):
 
     *shading* may be 'flat', or 'gouraud'
     """
-    def __init__(self, meshWidth, meshHeight, coordinates,
-                 antialiased=True, shading='flat', **kwargs):
-        super().__init__(**kwargs)
+    def __init__(self, *args, **kwargs):
+        # signature deprecation since="3.5": Change to new_sig after the
+        # deprecation has expired. Also remove setting __init__.__signature__.
+        old_sig = inspect.signature(
+            lambda meshWidth, meshHeight, coordinates,
+                   antialiased=True, shading='flat', **kwargs: None)
+        new_sig = inspect.signature(
+            lambda coordinates, *,
+                   antialiased=True, shading='flat', **kwargs: None)
+        try:
+            bound = new_sig.bind(*args, **kwargs)
+        except TypeError as exc:
+            try:
+                print(args, kwargs)
+                bound = old_sig.bind(*args, **kwargs)
+            except TypeError:
+                raise exc  # the new_sig binding error makes more sense
+                # user passed in args using the old call convention
+            else:
+                bound.apply_defaults()
+                meshWidth = bound.arguments['meshWidth']
+                meshHeight = bound.arguments['meshHeight']
+                coordinates = bound.arguments['coordinates']
+                antialiased = bound.arguments['antialiased']
+                shading = bound.arguments['shading']
+                kwargs = bound.arguments['kwargs']
+                _api.warn_deprecated(
+                    "3.5",
+                    message="This usage of Quadmesh is deprecated: Parameters "
+                        "meshWidth and meshHights will be removed; "
+                        "coordinates must be 2D; all parameters except "
+                        "coordinates will be keyword-only.")
+                super().__init__(**kwargs)
+                self._coordinates = np.asarray(coordinates, np.float64)\
+                        .reshape((meshHeight + 1, meshWidth + 1, 2))
+        else:
+            bound.apply_defaults()
+            coordinates = bound.arguments['coordinates']
+            antialiased = bound.arguments['antialiased']
+            shading = bound.arguments['shading']
+            kwargs = bound.arguments['kwargs']
+            super().__init__(**kwargs)
+            self._coordinates = np.asarray(coordinates, np.float64)
+            shape = self._coordinates.shape
+            print('XX', self._coordinates.ndim, shape)
+            if (self._coordinates.ndim != 3 or shape[-1] != 2):
+                raise ValueError(
+                    "coordinates must be a (N, M, 2) array-like, but got "
+                    f"{shape}")
+            meshWidth = shape[1] - 1
+            meshHeight = shape[0] - 1
+            # end of signature deprecation code
+
         self._meshWidth = meshWidth
         self._meshHeight = meshHeight
-        # By converting to floats now, we can avoid that on every draw.
-        self._coordinates = np.asarray(coordinates, float).reshape(
-            (meshHeight + 1, meshWidth + 1, 2))
         self._antialiased = antialiased
         self._shading = shading
 
         self._bbox = transforms.Bbox.unit()
         self._bbox.update_from_data_xy(coordinates.reshape(
             ((meshWidth + 1) * (meshHeight + 1), 2)))
 
+    # Only needed during signature deprecation
+    __init__.__signature__ = inspect.signature(
+        lambda self, coordinates, *,
+               antialiased=True, shading='flat', **kwargs: None)
+
     def get_paths(self):
         if self._paths is None:
             self.set_paths()
diff --git a/lib/matplotlib/tests/test_collections.py b/lib/matplotlib/tests/test_collections.py
@@ -714,6 +714,78 @@ def test_singleton_autolim():
     np.testing.assert_allclose(ax.get_xlim(), [-0.06, 0.06])
 
 
+@pytest.mark.parametrize('flat_ref, kwargs', [
+    (True, {}),
+    (False, {}),
+    (True, dict(antialiased=False)),
+    (False, dict(transform='__initialization_delayed__')),
+])
+@check_figures_equal(extensions=['png'])
+def test_quadmesh_deprecated_signature(
+        fig_test, fig_ref, flat_ref, kwargs):
+    # test that the new and old quadmesh signature produce the same results
+    # remove when the old QuadMesh.__init__ signature expires (v3.5+2)
+    from matplotlib.collections import QuadMesh
+
+    x = [0, 1, 2, 3.]
+    y = [1, 2, 3.]
+    X, Y = np.meshgrid(x, y)
+    X += 0.2 * Y
+    coords = np.stack([X, Y], axis=-1)
+    assert coords.shape == (3, 4, 2)
+    C = np.linspace(0, 2, 12).reshape(3, 4)
+
+    ax = fig_test.add_subplot()
+    ax.set(xlim=(0, 5), ylim=(0, 4))
+    if 'transform' in kwargs:
+        kwargs['transform'] = mtransforms.Affine2D().scale(1.2) + ax.transData
+    qmesh = QuadMesh(coords, **kwargs)
+    qmesh.set_array(C)
+    ax.add_collection(qmesh)
+
+    ax = fig_ref.add_subplot()
+    ax.set(xlim=(0, 5), ylim=(0, 4))
+    if 'transform' in kwargs:
+        kwargs['transform'] = mtransforms.Affine2D().scale(1.2) + ax.transData
+    with pytest.warns(MatplotlibDeprecationWarning):
+        qmesh = QuadMesh(4 - 1, 3 - 1,
+                         coords.copy().reshape(-1, 2) if flat_ref else coords,
+                         **kwargs)
+    qmesh.set_array(C.flatten() if flat_ref else C)
+    ax.add_collection(qmesh)
+
+
+@check_figures_equal(extensions=['png'])
+def test_quadmesh_deprecated_positional(fig_test, fig_ref):
+    # test that positional parameters are still accepted with the old signature
+    # and work correctly
+    # remove when the old QuadMesh.__init__ signature expires (v3.5+2)
+    from matplotlib.collections import QuadMesh
+
+    x = [0, 1, 2, 3.]
+    y = [1, 2, 3.]
+    X, Y = np.meshgrid(x, y)
+    X += 0.2 * Y
+    coords = np.stack([X, Y], axis=-1)
+    assert coords.shape == (3, 4, 2)
+    coords_flat = coords.copy().reshape(-1, 2)
+    C = np.linspace(0, 2, 12).reshape(3, 4)
+
+    ax = fig_test.add_subplot()
+    ax.set(xlim=(0, 5), ylim=(0, 4))
+    qmesh = QuadMesh(coords, antialiased=False, shading='gouraud')
+    qmesh.set_array(C)
+    ax.add_collection(qmesh)
+
+    ax = fig_ref.add_subplot()
+    ax.set(xlim=(0, 5), ylim=(0, 4))
+    with pytest.warns(MatplotlibDeprecationWarning):
+        qmesh = QuadMesh(4 - 1, 3 - 1, coords.copy().reshape(-1, 2),
+                         False, 'gouraud')
+    qmesh.set_array(C)
+    ax.add_collection(qmesh)
+
+
 def test_quadmesh_set_array():
     x = np.arange(4)
     y = np.arange(4)
