Rename quiver argument

dstansby · dstansby · commit 99c815126c94 · 2021-09-05T13:42:54.000+01:00
diff --git a/doc/api/next_api_changes/behavior/20962-DS.rst b/doc/api/next_api_changes/behavior/20962-DS.rst
@@ -8,3 +8,9 @@ the `~.units.ConversionInterface.default_units` and
 argument to be a `~.cm.ScalarMappable` object, and
 `~.units.ConversionInterface.convert` must be able to convert data of more than
 one dimension (e.g. when plotting images the data is 2D).
+
+The ``Quiver`` ``units`` property is renamed ``arrow_units``
+------------------------------------------------------------
+This is to clarify the meaning of this property, and enable support for color
+mapped data with units in the future. The corresponding keyword argument to
+`~.quiver.Quiver` is also renamed. 
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -89,7 +89,8 @@
     use *color* instead.  The size of *C* must match the number of arrow
     locations.
 
-units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default: 'width'
+arrow_units : {'width', 'height', 'dots', 'inches', 'x', 'y', 'xy'}, default:
+'width'
     The arrow dimensions (except for *length*) are measured in multiples of
     this unit.
 
@@ -99,9 +100,9 @@
     - 'dots', 'inches': Pixels or inches based on the figure dpi.
     - 'x', 'y', 'xy': *X*, *Y* or :math:`\\sqrt{X^2 + Y^2}` in data units.
 
-    The arrows scale differently depending on the units.  For
+    The arrows scale differently depending on the arrow units.  For
     'x' or 'y', the arrows get larger as one zooms in; for other
-    units, the arrow size is independent of the zoom state.  For
+    arrow units, the arrow size is independent of the zoom state.  For
     'width or 'height', the arrow size increases with the width and
     height of the axes, respectively, when the window is resized;
     for 'dots' or 'inches', resizing does not change the arrows.
@@ -151,7 +152,7 @@
     ``angles='xy', scale_units='xy', scale=1``.
 
 width : float, optional
-    Shaft width in arrow units; default depends on choice of units,
+    Shaft width in arrow units; default depends on choice of arrow units,
     above, and number of vectors; a typical starting value is about
     0.005 times the width of the plot.
 
@@ -466,11 +467,13 @@ class Quiver(mcollections.PolyCollection):
 
     _PIVOT_VALS = ('tail', 'middle', 'tip')
 
+    @_api.rename_parameter('3.6', 'units', 'arrow_units')
     @docstring.Substitution(_quiver_doc)
     def __init__(self, ax, *args,
                  scale=None, headwidth=3, headlength=5, headaxislength=4.5,
-                 minshaft=1, minlength=1, units='width', scale_units=None,
-                 angles='uv', width=None, color='k', pivot='tail', **kw):
+                 minshaft=1, minlength=1, arrow_units='width',
+                 scale_units=None, angles='uv', width=None, color='k',
+                 pivot='tail', **kw):
         """
         The constructor takes one required argument, an Axes
         instance, followed by the args and kwargs described
@@ -504,7 +507,7 @@ def __init__(self, ax, *args,
         super().__init__([], offsets=self.XY, transOffset=self.transform,
                          closed=False, **kw)
 
-        self.units = units
+        self.arrow_units = arrow_units
         self.polykw = kw
         self.set_UVC(U, V, C)
         self._initialized = False
@@ -522,11 +525,36 @@ def on_dpi_change(fig):
 
         self._cid = ax.figure.callbacks.connect('dpi_changed', on_dpi_change)
 
+    @property
+    def units(self):
+        _api.warn_deprecated(
+            '3.6',
+            message='%(name)s is deprecated since %(since)s. Use '
+            '%(alternative)s instead.',
+            name='Quiver.units',
+            alternative='Quiver.arrow_units')
+        return self.arrow_units
+
+    @units.setter
+    def units(self, val):
+        # Avoid emitting a warning when `ScalarMappable.__init__` sets this
+        # to None
+        if val is not None:
+            _api.warn_deprecated(
+                '3.6',
+                message='%(name)s is deprecated since %(since)s. Use '
+                '%(alternative)s instead.',
+                name='Quiver.units',
+                alternative='Quiver.arrow_units')
+        self.arrow_units = val
+
     def _convert_mappable_units(self, A):
         """
         Since Quiver already has a .units attribute for another purpose, it's
         not yet possible to support units on the ScalarMappable part, so
         override convert units to be a no-op.
+
+        This method can be removed when the .units deprecation expires.
         """
         return A
 
@@ -602,15 +630,15 @@ def set_UVC(self, U, V, C=None):
         self._new_UV = True
         self.stale = True
 
-    def _dots_per_unit(self, units):
+    def _dots_per_unit(self, arrow_units):
         """
         Return a scale factor for converting from units to pixels
         """
-        if units in ('x', 'y', 'xy'):
-            if units == 'x':
+        if arrow_units in ('x', 'y', 'xy'):
+            if arrow_units == 'x':
                 dx0 = self.axes.viewLim.width
                 dx1 = self.axes.bbox.width
-            elif units == 'y':
+            elif arrow_units == 'y':
                 dx0 = self.axes.viewLim.height
                 dx1 = self.axes.bbox.height
             else:  # 'xy' is assumed
@@ -622,24 +650,24 @@ def _dots_per_unit(self, units):
                 dx0 = np.hypot(dxx0, dyy0)
             dx = dx1 / dx0
         else:
-            if units == 'width':
+            if arrow_units == 'width':
                 dx = self.axes.bbox.width
-            elif units == 'height':
+            elif arrow_units == 'height':
                 dx = self.axes.bbox.height
-            elif units == 'dots':
+            elif arrow_units == 'dots':
                 dx = 1.0
-            elif units == 'inches':
+            elif arrow_units == 'inches':
                 dx = self.axes.figure.dpi
             else:
-                raise ValueError(f'Unrecognized units: {units}')
+                raise ValueError(f'Unrecognized arrow units: {arrow_units}')
         return dx
 
     def _set_transform(self):
         """
         Set the PolyCollection transform to go
         from arrow width units to pixels.
         """
-        dx = self._dots_per_unit(self.units)
+        dx = self._dots_per_unit(self.arrow_units)
         self._trans_scale = dx  # pixels per arrow width unit
         trans = transforms.Affine2D().scale(dx)
         self.set_transform(trans)
diff --git a/lib/matplotlib/tests/test_quiver.py b/lib/matplotlib/tests/test_quiver.py
@@ -5,6 +5,7 @@
 import pytest
 
 from matplotlib import pyplot as plt
+from matplotlib._api import MatplotlibDeprecationWarning
 from matplotlib.testing.decorators import image_comparison
 
 
@@ -168,7 +169,7 @@ def test_quiver_key_xy():
         ax.set_xlim(-1, 8)
         ax.set_ylim(-0.2, 0.2)
         q = ax.quiver(X, Y, U, V, pivot='middle',
-                      units='xy', width=0.05,
+                      arrow_units='xy', width=0.05,
                       scale=2, scale_units='xy',
                       angles=angle_str)
         for x, angle in zip((0.2, 0.5, 0.8), (0, 45, 90)):
@@ -277,3 +278,25 @@ def test_quiver_setuvc_numbers():
 
     q = ax.quiver(X, Y, U, V)
     q.set_UVC(0, 1)
+
+
+def test_units_deprecation():
+    fig, ax = plt.subplots()
+
+    X, Y = np.meshgrid(np.arange(2), np.arange(2))
+    U = V = np.ones_like(X)
+
+    with pytest.warns(MatplotlibDeprecationWarning,
+                      match="renamed 'arrow_units'"):
+        q = ax.quiver(X, Y, U, V, units='xy')
+
+    with pytest.warns(MatplotlibDeprecationWarning,
+                      match="Quiver.units is deprecated"):
+        assert q.units == 'xy'
+
+    assert q.arrow_units == 'xy'
+
+    with pytest.warns(MatplotlibDeprecationWarning,
+                      match="Quiver.units is deprecated"):
+        q.units = 'x'
+    assert q.arrow_units == 'x'
diff --git a/lib/matplotlib/tests/test_triangulation.py b/lib/matplotlib/tests/test_triangulation.py
@@ -816,7 +816,7 @@ def dipole_potential(x, y):
                    linewidths=[2.0, 1.0, 1.0, 1.0])
     # Plots direction of the electrical vector field
     plt.quiver(triang.x, triang.y, Ex/E_norm, Ey/E_norm,
-               units='xy', scale=10., zorder=3, color='blue',
+               arrow_units='xy', scale=10., zorder=3, color='blue',
                width=0.007, headwidth=3., headlength=4.)
     # We are leaving ax.use_sticky_margins as True, so the
     # view limits are the contour data limits.
