API : tighten validation on pivot in Quiver

tacaswell · tacaswell · commit af170517defe · 2014-12-29T16:20:03.000-08:00
only accept {'mid', 'middle', 'tip', 'tail'} instead of being super permissive. Closes #3951
diff --git a/doc/api/api_changes/2014-12-28_quiver.rst b/doc/api/api_changes/2014-12-28_quiver.rst
@@ -0,0 +1,12 @@
+Tighted input validation on 'pivot' kwarg to quiver
+```````````````````````````````````````````````````
+
+Tightened validation so that only {'tip', 'tail', 'mid', and 'middle'}
+(but any capitalization) are valid values for the 'pivot' kwarg in
+the `Quiver.__init__` (and hence `Axes.quiver` and
+`plt.quiver` which both fully delegate to `Quiver`).  Previously any
+input matching 'mid.*' would be interpreted as 'middle', 'tip.*' as
+'tip' and any string not matching one of those patterns as 'tail'.
+
+The value of `Quiver.pivot` is normalized to be in the set {'tip',
+'tail', 'middle'} in `Quiver.__init__`.
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -136,7 +136,7 @@
     is less than this, plot a dot (hexagon) of this diameter instead.
     Default is 1.
 
-  *pivot*: [ 'tail' | 'middle' | 'tip' ]
+  *pivot*: [ 'tail' | 'mid' | 'middle' | 'tip' ]
     The part of the arrow that is at the grid point; the arrow rotates
     about this point, hence the name *pivot*.
 
@@ -405,6 +405,8 @@ class Quiver(mcollections.PolyCollection):
     in the draw() method.
     """
 
+    _PIVOT_VALS = ('tail', 'mid', 'middle', 'tip')
+
     @docstring.Substitution(_quiver_doc)
     def __init__(self, ax, *args, **kw):
         """
@@ -430,7 +432,18 @@ def __init__(self, ax, *args, **kw):
         self.angles = kw.pop('angles', 'uv')
         self.width = kw.pop('width', None)
         self.color = kw.pop('color', 'k')
-        self.pivot = kw.pop('pivot', 'tail')
+
+        pivot = kw.pop('pivot', 'tail').lower()
+        # validate pivot
+        if pivot not in self._PIVOT_VALS:
+            raise ValueError(
+                'pivot must be one of {keys}, you passed {inp}'.format(
+                      keys=self._PIVOT_VALS, inp=pivot))
+        # normalize to 'middle'
+        if pivot == 'mid':
+            pivot = 'middle'
+        self.pivot = pivot
+
         self.transform = kw.pop('transform', ax.transData)
         kw.setdefault('facecolors', self.color)
         kw.setdefault('linewidths', (0,))
@@ -681,9 +694,9 @@ def _h_arrows(self, length):
         # Now select X0, Y0 if short, otherwise X, Y
         cbook._putmask(X, short, X0)
         cbook._putmask(Y, short, Y0)
-        if self.pivot[:3] == 'mid':
+        if self.pivot == 'middle':
             X -= 0.5 * X[:, 3, np.newaxis]
-        elif self.pivot[:3] == 'tip':
+        elif self.pivot == 'tip':
             X = X - X[:, 3, np.newaxis]   # numpy bug? using -= does not
                                           # work here unless we multiply
                                           # by a float first, as with 'mid'.
