Add helper function to check that an argument is in a list of strings.

anntzer · anntzer · commit 0ab7dab9ccc4 · 2018-09-24T08:03:12.000+02:00
diff --git a/doc/api/next_api_changes/2018-09-22-AL.rst b/doc/api/next_api_changes/2018-09-22-AL.rst
@@ -0,0 +1,5 @@
+Changed exceptions
+``````````````````
+
+- `mpl_toolkits.axes_grid1.axes_size.GetExtentHelper` now raises `ValueError`
+  for invalid directions instead of `KeyError`.
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1318,8 +1318,8 @@ def set_adjustable(self, adjustable, share=False):
         if adjustable == 'box-forced':
             cbook.warn_deprecated(
                 "2.2", "box-forced", obj_type="keyword argument")
-        if adjustable not in ('box', 'datalim', 'box-forced'):
-            raise ValueError("argument must be 'box', or 'datalim'")
+        cbook._check_enum(['box', 'datalim', 'box-forced'],
+                          adjustable=adjustable)
         if share:
             axes = set(self._shared_x_axes.get_siblings(self)
                        + self._shared_y_axes.get_siblings(self))
@@ -2726,9 +2726,7 @@ def grid(self, b=None, which='major', axis='both', **kwargs):
         elif b is not None:
             b = _string_to_bool(b)
 
-        if axis not in ['x', 'y', 'both']:
-            raise ValueError("The argument 'axis' must be one of 'x', 'y' or "
-                             "'both'.")
+        cbook._check_enum(['x', 'y', 'both'], axis=axis)
         if axis in ['x', 'both']:
             self.xaxis.grid(b, which=which, **kwargs)
         if axis in ['y', 'both']:
@@ -2949,8 +2947,7 @@ def tick_params(self, axis='both', **kwargs):
         also be red.  Gridlines will be red and translucent.
 
         """
-        if axis not in ['x', 'y', 'both']:
-            raise ValueError("axis must be one of 'x', 'y' or 'both'")
+        cbook._check_enum(['x', 'y', 'both'], axis=axis)
         if axis in ['x', 'both']:
             xkw = dict(kwargs)
             xkw.pop('left', None)
diff --git a/lib/matplotlib/axes/_subplots.py b/lib/matplotlib/axes/_subplots.py
@@ -1,6 +1,6 @@
 import functools
 
-from matplotlib import docstring
+from matplotlib import cbook, docstring
 import matplotlib.artist as martist
 from matplotlib.axes._axes import Axes
 from matplotlib.gridspec import GridSpec, SubplotSpec
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -195,9 +195,7 @@ def _set_labelrotation(self, labelrotation):
         else:
             mode = 'default'
             angle = labelrotation
-        if mode not in ('auto', 'default'):
-            raise ValueError("Label rotation mode must be 'default' or "
-                             "'auto', not '{}'.".format(mode))
+        cbook._check_enum(['auto', 'default'], **{'label rotation mode': mode})
         self._labelrotation = (mode, angle)
 
     def apply_tickdir(self, tickdir):
@@ -1278,8 +1276,7 @@ def get_ticklabels(self, minor=False, which=None):
             elif which == 'both':
                 return self.get_majorticklabels() + self.get_minorticklabels()
             else:
-                raise ValueError("`which` must be one of ('minor', 'major', "
-                                 "'both') not " + str(which))
+                cbook._check_enum(['major', 'minor', 'both'], which=which)
         if minor:
             return self.get_minorticklabels()
         return self.get_majorticklabels()
@@ -1443,9 +1440,7 @@ def grid(self, b=None, which='major', **kwargs):
                               'enabled.')
             b = True
         which = which.lower()
-        if which not in ['major', 'minor', 'both']:
-            raise ValueError("The argument 'which' must be one of 'major', "
-                             "'minor' or 'both'.")
+        cbook._check_enum(['major', 'minor', 'both'], which=which)
         gridkw = {'grid_' + item[0]: item[1] for item in kwargs.items()}
 
         if which in ['minor', 'both']:
diff --git a/lib/matplotlib/backends/backend_ps.py b/lib/matplotlib/backends/backend_ps.py
@@ -950,12 +950,8 @@ def _print_ps(self, outfile, format, *args,
                                (papertype, ', '.join(papersize)))
 
         orientation = orientation.lower()
-        if orientation == 'landscape':
-            isLandscape = True
-        elif orientation == 'portrait':
-            isLandscape = False
-        else:
-            raise RuntimeError('Orientation must be "portrait" or "landscape"')
+        cbook._check_enum(['landscape', 'portrait'], orientation=orientation)
+        isLandscape = (orientation == 'landscape')
 
         self.figure.set_dpi(72)  # Override the dpi kwarg
 
diff --git a/lib/matplotlib/backends/backend_webagg_core.py b/lib/matplotlib/backends/backend_webagg_core.py
@@ -20,9 +20,9 @@
 import numpy as np
 import tornado
 
+from matplotlib import backend_bases, cbook, _png
 from matplotlib.backends import backend_agg
 from matplotlib.backend_bases import _Backend
-from matplotlib import backend_bases, _png
 
 
 # http://www.cambiaresearch.com/articles/15/javascript-char-codes-key-codes
@@ -162,10 +162,8 @@ def set_image_mode(self, mode):
         Note: diff images may not contain transparency, therefore upon
         draw this mode may be changed if the resulting image has any
         transparent component.
-
         """
-        if mode not in ['full', 'diff']:
-            raise ValueError('image mode must be either full or diff.')
+        cbook._check_enum(['full', 'diff'], mode=mode)
         if self._current_image_mode != mode:
             self._current_image_mode = mode
             self.handle_send_image_mode(None)
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -2062,6 +2062,12 @@ def _unmultiplied_rgba8888_to_premultiplied_argb32(rgba8888):
 
 
 def _check_and_log_subprocess(command, logger, **kwargs):
+    """
+    Run *command* using `subprocess.check_output`.  If it succeeds, return the
+    output (stdout and stderr); if not, raise an exception whose text includes
+    the failed command and captured output.  Both the command and the output
+    are logged at DEBUG level on *logger*.
+    """
     logger.debug(command)
     try:
         report = subprocess.check_output(
@@ -2075,3 +2081,15 @@ def _check_and_log_subprocess(command, logger, **kwargs):
             .format(command, exc.output.decode('utf-8')))
     logger.debug(report)
     return report
+
+
+def _check_enum(values, **kwargs):
+    """
+    For each *key, value* pair in *kwargs*, check that *value* is in *values*;
+    if not, raise an appropriate ValueError.
+    """
+    for k, v in kwargs.items():
+        if v not in values:
+            raise ValueError(
+                "{!r} is not a valid value for {}; supported values are {}"
+                .format(v, k, ', '.join(map(repr, values))))
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -467,8 +467,7 @@ def set_offset_position(self, offset_position):
         ----------
         offset_position : {'screen', 'data'}
         """
-        if offset_position not in ('screen', 'data'):
-            raise ValueError("offset_position must be 'screen' or 'data'")
+        cbook._check_enum(['screen', 'data'], offset_position=offset_position)
         self._offset_position = offset_position
         self.stale = True
 
@@ -1383,7 +1382,8 @@ def __init__(self,
                         coord1 in positions]
             self._is_horizontal = False
         else:
-            raise ValueError("orientation must be 'horizontal' or 'vertical'")
+            cbook._check_enum(
+                ['horizontal', 'vertical'], orientation=orientation)
 
         LineCollection.__init__(self,
                                 segments,
@@ -1479,7 +1479,8 @@ def set_orientation(self, orientation=None):
         elif orientation.lower() == 'vertical':
             is_horizontal = False
         else:
-            raise ValueError("orientation must be 'horizontal' or 'vertical'")
+            cbook._check_enum(
+                ['horizontal', 'vertical'], orientation=orientation)
 
         if is_horizontal == self.is_horizontal():
             return
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -871,9 +871,7 @@ def __init__(self, ax, *args,
         else:
             self.logscale = False
 
-        if self.origin not in [None, 'lower', 'upper', 'image']:
-            raise ValueError("If given, *origin* must be one of [ 'lower' |"
-                             " 'upper' | 'image']")
+        cbook._check_enum([None, 'lower', 'upper', 'image'], origin=origin)
         if self.extent is not None and len(self.extent) != 4:
             raise ValueError("If given, *extent* must be '[ *None* |"
                              " (x0,x1,y0,y1) ]'")
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1483,23 +1483,16 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
             sharex = "all" if sharex else "none"
         if isinstance(sharey, bool):
             sharey = "all" if sharey else "none"
-        share_values = ["all", "row", "col", "none"]
-        if sharex not in share_values:
-            # This check was added because it is very easy to type
-            # `subplots(1, 2, 1)` when `subplot(1, 2, 1)` was intended.
-            # In most cases, no error will ever occur, but mysterious behavior
-            # will result because what was intended to be the subplot index is
-            # instead treated as a bool for sharex.
-            if isinstance(sharex, Integral):
-                warnings.warn(
-                    "sharex argument to subplots() was an integer. "
-                    "Did you intend to use subplot() (without 's')?")
-
-            raise ValueError("sharex [%s] must be one of %s" %
-                             (sharex, share_values))
-        if sharey not in share_values:
-            raise ValueError("sharey [%s] must be one of %s" %
-                             (sharey, share_values))
+        # This check was added because it is very easy to type
+        # `subplots(1, 2, 1)` when `subplot(1, 2, 1)` was intended.
+        # In most cases, no error will ever occur, but mysterious behavior
+        # will result because what was intended to be the subplot index is
+        # instead treated as a bool for sharex.
+        if isinstance(sharex, Integral):
+            warnings.warn("sharex argument to subplots() was an integer. "
+                          "Did you intend to use subplot() (without 's')?")
+        cbook._check_enum(["all", "row", "col", "none"],
+                          sharex=sharex, sharey=sharey)
         if subplot_kw is None:
             subplot_kw = {}
         if gridspec_kw is None:
diff --git a/lib/matplotlib/font_manager.py b/lib/matplotlib/font_manager.py
@@ -720,8 +720,7 @@ def set_style(self, style):
         """
         if style is None:
             style = rcParams['font.style']
-        if style not in ('normal', 'italic', 'oblique'):
-            raise ValueError("style must be normal, italic or oblique")
+        cbook._check_enum(['normal', 'italic', 'oblique'], style=style)
         self._slant = style
     set_slant = set_style
 
@@ -731,8 +730,7 @@ def set_variant(self, variant):
         """
         if variant is None:
             variant = rcParams['font.variant']
-        if variant not in ('normal', 'small-caps'):
-            raise ValueError("variant must be normal or small-caps")
+        cbook._check_enum(['normal', 'small-caps'], variant=variant)
         self._variant = variant
 
     def set_weight(self, weight):
diff --git a/lib/matplotlib/mathtext.py b/lib/matplotlib/mathtext.py
@@ -3348,14 +3348,10 @@ def parse(self, s, dpi = 72, prop = None):
             font_output = StandardPsFonts(prop)
         else:
             backend = self._backend_mapping[self._output]()
-            fontset = rcParams['mathtext.fontset']
-            fontset_class = self._font_type_mapping.get(fontset.lower())
-            if fontset_class is not None:
-                font_output = fontset_class(prop, backend)
-            else:
-                raise ValueError(
-                    "mathtext.fontset must be either 'cm', 'dejavuserif', "
-                    "'dejavusans', 'stix', 'stixsans', or 'custom'")
+            fontset = rcParams['mathtext.fontset'].lower()
+            cbook._check_enum(self._font_type_mapping, fontset=fontset)
+            fontset_class = self._font_type_mapping[fontset]
+            font_output = fontset_class(prop, backend)
 
         fontsize = prop.get_size_in_points()
 
diff --git a/lib/matplotlib/projections/geo.py b/lib/matplotlib/projections/geo.py
@@ -1,6 +1,6 @@
 import numpy as np
 
-from matplotlib import rcParams
+from matplotlib import cbook, rcParams
 from matplotlib.axes import Axes
 import matplotlib.axis as maxis
 from matplotlib.patches import Circle
@@ -118,9 +118,7 @@ def _get_affine_transform(self):
             .translate(0.5, 0.5)
 
     def get_xaxis_transform(self, which='grid'):
-        if which not in ['tick1', 'tick2', 'grid']:
-            raise ValueError(
-                "'which' must be one of 'tick1', 'tick2', or 'grid'")
+        cbook._check_enum(['tick1', 'tick2', 'grid'], which=which)
         return self._xaxis_transform
 
     def get_xaxis_text1_transform(self, pad):
@@ -130,9 +128,7 @@ def get_xaxis_text2_transform(self, pad):
         return self._xaxis_text2_transform, 'top', 'center'
 
     def get_yaxis_transform(self, which='grid'):
-        if which not in ['tick1', 'tick2', 'grid']:
-            raise ValueError(
-                "'which' must be one of 'tick1', 'tick2', or 'grid'")
+        cbook._check_enum(['tick1', 'tick2', 'grid'], which=which)
         return self._yaxis_transform
 
     def get_yaxis_text1_transform(self, pad):
diff --git a/lib/matplotlib/projections/polar.py b/lib/matplotlib/projections/polar.py
@@ -3,12 +3,12 @@
 
 import numpy as np
 
+from matplotlib import cbook, rcParams
 from matplotlib.axes import Axes
 import matplotlib.axis as maxis
 import matplotlib.markers as mmarkers
 import matplotlib.patches as mpatches
 import matplotlib.path as mpath
-from matplotlib import rcParams
 import matplotlib.ticker as mticker
 import matplotlib.transforms as mtransforms
 import matplotlib.spines as mspines
@@ -969,9 +969,7 @@ def _set_lim_and_transforms(self):
             self._r_label_position + self.transData)
 
     def get_xaxis_transform(self, which='grid'):
-        if which not in ['tick1', 'tick2', 'grid']:
-            raise ValueError(
-                "'which' must be one of 'tick1', 'tick2', or 'grid'")
+        cbook._check_enum(['tick1', 'tick2', 'grid'], which=which)
         return self._xaxis_transform
 
     def get_xaxis_text1_transform(self, pad):
@@ -986,8 +984,7 @@ def get_yaxis_transform(self, which='grid'):
         elif which == 'grid':
             return self._yaxis_transform
         else:
-            raise ValueError(
-                "'which' must be one of 'tick1', 'tick2', or 'grid'")
+            cbook._check_enum(['tick1', 'tick2', 'grid'], which=which)
 
     def get_yaxis_text1_transform(self, pad):
         thetamin, thetamax = self._realViewLim.intervalx
@@ -1141,15 +1138,14 @@ def set_theta_direction(self, direction):
            Theta increases in the counterclockwise direction
         """
         mtx = self._direction.get_matrix()
-        if direction in ('clockwise',):
+        if direction in ('clockwise', -1):
             mtx[0, 0] = -1
-        elif direction in ('counterclockwise', 'anticlockwise'):
+        elif direction in ('counterclockwise', 'anticlockwise', 1):
             mtx[0, 0] = 1
-        elif direction in (1, -1):
-            mtx[0, 0] = direction
         else:
-            raise ValueError(
-                "direction must be 1, -1, clockwise or counterclockwise")
+            cbook._check_enum(
+                [-1, 1, 'clockwise', 'counterclockwise', 'anticlockwise'],
+                direction=direction)
         self._direction.invalidate()
 
     def get_theta_direction(self):
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -24,7 +24,7 @@
 import matplotlib.transforms as transforms
 import matplotlib.text as mtext
 import matplotlib.artist as martist
-from matplotlib import docstring
+from matplotlib import cbook, docstring
 import matplotlib.font_manager as font_manager
 from matplotlib.cbook import delete_masked_points
 from matplotlib.patches import CirclePolygon
@@ -462,10 +462,7 @@ def __init__(self, ax, *args,
         if pivot.lower() == 'mid':
             pivot = 'middle'
         self.pivot = pivot.lower()
-        if self.pivot not in self._PIVOT_VALS:
-            raise ValueError(
-                'pivot must be one of {keys}, you passed {inp}'.format(
-                      keys=self._PIVOT_VALS, inp=pivot))
+        cbook._check_enum(self._PIVOT_VALS, pivot=self.pivot)
 
         self.transform = kw.pop('transform', ax.transData)
         kw.setdefault('facecolors', self.color)
diff --git a/lib/matplotlib/scale.py b/lib/matplotlib/scale.py
@@ -236,19 +236,19 @@ def __init__(self, axis, **kwargs):
             base = kwargs.pop('basex', 10.0)
             subs = kwargs.pop('subsx', None)
             nonpos = kwargs.pop('nonposx', 'clip')
+            cbook._check_enum(['mask', 'clip'], nonposx=nonpos)
         else:
             base = kwargs.pop('basey', 10.0)
             subs = kwargs.pop('subsy', None)
             nonpos = kwargs.pop('nonposy', 'clip')
+            cbook._check_enum(['mask', 'clip'], nonposy=nonpos)
 
         if len(kwargs):
             raise ValueError(("provided too many kwargs, can only pass "
                               "{'basex', 'subsx', nonposx'} or "
                               "{'basey', 'subsy', nonposy'}.  You passed ") +
                              "{!r}".format(kwargs))
 
-        if nonpos not in ['mask', 'clip']:
-            raise ValueError("nonposx, nonposy kwarg must be 'mask' or 'clip'")
         if base <= 0 or base == 1:
             raise ValueError('The log base cannot be <= 0 or == 1')
 
@@ -511,9 +511,7 @@ def __init__(self, axis, nonpos='mask'):
           values beyond ]0, 1[ can be masked as invalid, or clipped to a number
           very close to 0 or 1
         """
-        if nonpos not in ['mask', 'clip']:
-            raise ValueError("nonposx, nonposy kwarg must be 'mask' or 'clip'")
-
+        cbook._check_enum(['mask', 'clip'], nonpos=nonpos)
         self._transform = LogitTransform(nonpos)
 
     def get_transform(self):
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
diff --git a/lib/matplotlib/tri/tripcolor.py b/lib/matplotlib/tri/tripcolor.py
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py
diff --git a/lib/mpl_toolkits/axes_grid1/axes_size.py b/lib/mpl_toolkits/axes_grid1/axes_size.py
diff --git a/lib/mpl_toolkits/axisartist/axis_artist.py b/lib/mpl_toolkits/axisartist/axis_artist.py
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
