Use true positional args in check_foo APIs instead of simulating them.

Author: anntzer

lib/matplotlib/_api/__init__.py

@@ -58,22 +58,20 @@ def fget(self):
         return self._fget
 
 
-# In the following check_foo() functions, the first parameter starts with an
-# underscore because it is intended to be positional-only (e.g., so that
-# `_api.check_isinstance([...], types=foo)` doesn't fail.
+# In the following check_foo() functions, the first parameter is positional-only to make
+# e.g. `_api.check_isinstance([...], types=foo)` work.
 
-def check_isinstance(_types, **kwargs):
+def check_isinstance(types, /, **kwargs):
     """
     For each *key, value* pair in *kwargs*, check that *value* is an instance
-    of one of *_types*; if not, raise an appropriate TypeError.
+    of one of *types*; if not, raise an appropriate TypeError.
 
-    As a special case, a ``None`` entry in *_types* is treated as NoneType.
+    As a special case, a ``None`` entry in *types* is treated as NoneType.
 
     Examples
     --------
     >>> _api.check_isinstance((SomeClass, None), arg=arg)
     """
-    types = _types
     none_type = type(None)
     types = ((types,) if isinstance(types, type) else
              (none_type,) if types is None else
@@ -98,31 +96,31 @@ def type_name(tp):
                     type_name(type(v))))
 
 
-def check_in_list(_values, *, _print_supported_values=True, **kwargs):
+def check_in_list(values,  /, *, _print_supported_values=True, **kwargs):
     """
-    For each *key, value* pair in *kwargs*, check that *value* is in *_values*.
+    For each *key, value* pair in *kwargs*, check that *value* is in *values*;
+    if not, raise an appropriate ValueError.
 
     Parameters
     ----------
-    _values : iterable
+    values : iterable
         Sequence of values to check on.
     _print_supported_values : bool, default: True
-        Whether to print *_values* when raising ValueError.
+        Whether to print *values* when raising ValueError.
     **kwargs : dict
-        *key, value* pairs as keyword arguments to find in *_values*.
+        *key, value* pairs as keyword arguments to find in *values*.
 
     Raises
     ------
     ValueError
-        If any *value* in *kwargs* is not found in *_values*.
+        If any *value* in *kwargs* is not found in *values*.
 
     Examples
     --------
     >>> _api.check_in_list(["foo", "bar"], arg=arg, other_arg=other_arg)
     """
     if not kwargs:
         raise TypeError("No argument to check!")
-    values = _values
     for key, val in kwargs.items():
         if val not in values:
             msg = f"{val!r} is not a valid value for {key}"
@@ -131,10 +129,10 @@ def check_in_list(_values, *, _print_supported_values=True, **kwargs):
             raise ValueError(msg)
 
 
-def check_shape(_shape, **kwargs):
+def check_shape(shape, /, **kwargs):
     """
-    For each *key, value* pair in *kwargs*, check that *value* has the shape
-    *_shape*, if not, raise an appropriate ValueError.
+    For each *key, value* pair in *kwargs*, check that *value* has the shape *shape*;
+    if not, raise an appropriate ValueError.
 
     *None* in the shape is treated as a "free" size that can have any length.
     e.g. (None, 2) -> (N, 2)
@@ -147,42 +145,37 @@ def check_shape(_shape, **kwargs):
 
     >>> _api.check_shape((None, 2), arg=arg, other_arg=other_arg)
     """
-    target_shape = _shape
     for k, v in kwargs.items():
         data_shape = v.shape
 
-        if len(target_shape) != len(data_shape) or any(
-                t not in [s, None]
-                for t, s in zip(target_shape, data_shape)
-        ):
+        if (len(data_shape) != len(shape)
+                or any(s != t and t is not None for s, t in zip(data_shape, shape))):
             dim_labels = iter(itertools.chain(
                 'MNLIJKLH',
                 (f"D{i}" for i in itertools.count())))
             text_shape = ", ".join(str(n)
                                    if n is not None
                                    else next(dim_labels)
-                                   for n in target_shape)
-            if len(target_shape) == 1:
+                                   for n in shape)
+            if len(shape) == 1:
                 text_shape += ","
 
             raise ValueError(
-                f"{k!r} must be {len(target_shape)}D "
-                f"with shape ({text_shape}). "
-                f"Your input has shape {v.shape}."
+                f"{k!r} must be {len(shape)}D with shape ({text_shape}), "
+                f"but your input has shape {v.shape}"
             )
 
 
-def check_getitem(_mapping, **kwargs):
+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
+    *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()