Move cbook._check_getitem() to _api.check_getitem()

Author: timhoffm

lib/matplotlib/_api.py

@@ -71,3 +71,25 @@ def check_shape(_shape, **kwargs):
                 f"with shape ({text_shape}). "
                 f"Your input has shape {v.shape}."
             )
+
+
+def check_getitem(_mapping, **kwargs):
+    """
+    *kwargs* must consist of a single *key, value* pair.  If *key* is in
+    *_mapping*, return ``_mapping[value]``; else, raise an appropriate
+    ValueError.
+
+    Examples
+    --------
+    >>> _api.check_getitem({"foo": "bar"}, arg=arg)
+    """
+    mapping = _mapping
+    if len(kwargs) != 1:
+        raise ValueError("check_getitem takes a single keyword argument")
+    (k, v), = kwargs.items()
+    try:
+        return mapping[v]
+    except KeyError:
+        raise ValueError(
+            "{!r} is not a valid value for {}; supported values are {}"
+            .format(v, k, ', '.join(map(repr, mapping)))) from None

lib/matplotlib/axes/_axes.py

@@ -86,7 +86,7 @@ def get_title(self, loc="center"):
         titles = {'left': self._left_title,
                   'center': self.title,
                   'right': self._right_title}
-        title = cbook._check_getitem(titles, loc=loc.lower())
+        title = _api.check_getitem(titles, loc=loc.lower())
         return title.get_text()
 
     def set_title(self, label, fontdict=None, loc=None, pad=None, *, y=None,
@@ -149,7 +149,7 @@ def set_title(self, label, fontdict=None, loc=None, pad=None, *, y=None,
         titles = {'left': self._left_title,
                   'center': self.title,
                   'right': self._right_title}
-        title = cbook._check_getitem(titles, loc=loc.lower())
+        title = _api.check_getitem(titles, loc=loc.lower())
         default = {
             'fontsize': rcParams['axes.titlesize'],
             'fontweight': rcParams['axes.titleweight'],
@@ -7195,7 +7195,7 @@ def magnitude_spectrum(self, x, Fs=None, Fc=None, window=None,
                                               pad_to=pad_to, sides=sides)
         freqs += Fc
 
-        yunits = cbook._check_getitem(
+        yunits = _api.check_getitem(
             {None: 'energy', 'default': 'energy', 'linear': 'energy',
              'dB': 'dB'},
             scale=scale)

lib/matplotlib/axes/_base.py

@@ -3002,10 +3002,10 @@ def ticklabel_format(self, *, axis='both', style='', scilimits=None,
                 raise ValueError("scilimits must be a sequence of 2 integers"
                                  ) from err
         STYLES = {'sci': True, 'scientific': True, 'plain': False, '': None}
-        is_sci_style = cbook._check_getitem(STYLES, style=style)
+        is_sci_style = _api.check_getitem(STYLES, style=style)
         axis_map = {**{k: [v] for k, v in self._get_axis_map().items()},
                     'both': self._get_axis_list()}
-        axises = cbook._check_getitem(axis_map, axis=axis)
+        axises = _api.check_getitem(axis_map, axis=axis)
         try:
             for axis in axises:
                 if is_sci_style is not None:

lib/matplotlib/axis.py

@@ -2048,7 +2048,7 @@ def set_label_position(self, position):
         ----------
         position : {'top', 'bottom'}
         """
-        self.label.set_verticalalignment(cbook._check_getitem({
+        self.label.set_verticalalignment(_api.check_getitem({
             'top': 'baseline', 'bottom': 'top',
         }, position=position))
         self.label_position = position
@@ -2340,7 +2340,7 @@ def set_label_position(self, position):
         """
         self.label.set_rotation_mode('anchor')
         self.label.set_horizontalalignment('center')
-        self.label.set_verticalalignment(cbook._check_getitem({
+        self.label.set_verticalalignment(_api.check_getitem({
             'left': 'bottom', 'right': 'top',
         }, position=position))
         self.label_position = position
@@ -2425,7 +2425,7 @@ def set_offset_position(self, position):
         position : {'left', 'right'}
         """
         x, y = self.offsetText.get_position()
-        x = cbook._check_getitem({'left': 0, 'right': 1}, position=position)
+        x = _api.check_getitem({'left': 0, 'right': 1}, position=position)
 
         self.offsetText.set_ha(position)
         self.offsetText.set_position((x, y))

lib/matplotlib/backends/backend_cairo.py

@@ -24,7 +24,7 @@
             "cairo backend requires that pycairo>=1.11.0 or cairocffi "
             "is installed") from err
 
-from .. import cbook, font_manager
+from .. import _api, cbook, font_manager
 from matplotlib.backend_bases import (
     _Backend, _check_savefig_extra_args, FigureCanvasBase, FigureManagerBase,
     GraphicsContextBase, RendererBase)
@@ -358,7 +358,7 @@ def set_alpha(self, alpha):
         # one for False.
 
     def set_capstyle(self, cs):
-        self.ctx.set_line_cap(cbook._check_getitem(self._capd, capstyle=cs))
+        self.ctx.set_line_cap(_api.check_getitem(self._capd, capstyle=cs))
         self._capstyle = cs
 
     def set_clip_rectangle(self, rectangle):
@@ -401,7 +401,7 @@ def get_rgb(self):
         return self.ctx.get_source().get_rgba()[:3]
 
     def set_joinstyle(self, js):
-        self.ctx.set_line_join(cbook._check_getitem(self._joind, joinstyle=js))
+        self.ctx.set_line_join(_api.check_getitem(self._joind, joinstyle=js))
         self._joinstyle = js
 
     def set_linewidth(self, w):

lib/matplotlib/backends/backend_ps.py

@@ -817,7 +817,7 @@ def _print_ps(
         papertype = papertype.lower()
         _api.check_in_list(['auto', *papersize], papertype=papertype)
 
-        orientation = cbook._check_getitem(
+        orientation = _api.check_getitem(
             _Orientation, orientation=orientation.lower())
 
         printer = (self._print_figure_tex

lib/matplotlib/cbook/__init__.py

@@ -2281,28 +2281,6 @@ def type_name(tp):
                     type_name(type(v))))
 
 
-def _check_getitem(_mapping, **kwargs):
-    """
-    *kwargs* must consist of a single *key, value* pair.  If *key* is in
-    *_mapping*, return ``_mapping[value]``; else, raise an appropriate
-    ValueError.
-
-    Examples
-    --------
-    >>> cbook._check_getitem({"foo": "bar"}, arg=arg)
-    """
-    mapping = _mapping
-    if len(kwargs) != 1:
-        raise ValueError("_check_getitem takes a single keyword argument")
-    (k, v), = kwargs.items()
-    try:
-        return mapping[v]
-    except KeyError:
-        raise ValueError(
-            "{!r} is not a valid value for {}; supported values are {}"
-            .format(v, k, ', '.join(map(repr, mapping)))) from None
-
-
 class _classproperty:
     """
     Like `property`, but also triggers on access via the class, and it is the

lib/matplotlib/collections.py

@@ -1619,7 +1619,7 @@ def set_orientation(self, orientation=None):
         orientation : {'horizontal', 'vertical'}
         """
         try:
-            is_horizontal = cbook._check_getitem(
+            is_horizontal = _api.check_getitem(
                 {"horizontal": True, "vertical": False},
                 orientation=orientation)
         except ValueError:

lib/matplotlib/colorbar.py

@@ -461,7 +461,7 @@ def __init__(self, ax, cmap=None,
         self.values = values
         self.boundaries = boundaries
         self.extend = extend
-        self._inside = cbook._check_getitem(
+        self._inside = _api.check_getitem(
             {'neither': slice(0, None), 'both': slice(1, -1),
              'min': slice(1, None), 'max': slice(0, -1)},
             extend=extend)
@@ -1372,10 +1372,10 @@ def remove(self):
 
 def _normalize_location_orientation(location, orientation):
     if location is None:
-        location = cbook._check_getitem(
+        location = _api.check_getitem(
             {None: "right", "vertical": "right", "horizontal": "bottom"},
             orientation=orientation)
-    loc_settings = cbook._check_getitem({
+    loc_settings = _api.check_getitem({
         "left":   {"location": "left", "orientation": "vertical",
                    "anchor": (1.0, 0.5), "panchor": (0.0, 0.5), "pad": 0.10},
         "right":  {"location": "right", "orientation": "vertical",

lib/matplotlib/mathtext.py

@@ -24,7 +24,7 @@
 import numpy as np
 from PIL import Image
 
-from matplotlib import cbook, colors as mcolors, rcParams, _mathtext
+from matplotlib import _api, cbook, colors as mcolors, rcParams, _mathtext
 from matplotlib.ft2font import FT2Image, LOAD_NO_HINTING
 from matplotlib.font_manager import FontProperties
 # Backcompat imports, all are deprecated as of 3.4.
@@ -444,7 +444,7 @@ def _parse_cached(self, s, dpi, prop, force_standard_ps_fonts):
 
         fontset_class = (
             _mathtext.StandardPsFonts if force_standard_ps_fonts
-            else cbook._check_getitem(
+            else _api.check_getitem(
                 self._font_type_mapping, fontset=prop.get_math_fontfamily()))
         backend = self._backend_mapping[self._output]()
         font_output = fontset_class(prop, backend)