REF: separate indexer utilities from indexing.py (#27229)

Author: jbrockmendel

pandas/core/algorithms.py

@@ -50,6 +50,7 @@
 from pandas.core.dtypes.missing import isna, na_value_for_dtype
 
 from pandas.core import common as com
+from pandas.core.indexers import validate_indices
 
 _shared_docs = {}  # type: Dict[str, str]
 
@@ -1587,8 +1588,6 @@ def take(arr, indices, axis=0, allow_fill=False, fill_value=None):
     ...      fill_value=-10)
     array([ 10,  10, -10])
     """
-    from pandas.core.indexing import validate_indices
-
     if not is_array_like(arr):
         arr = np.asarray(arr)
 

pandas/core/indexers.py

@@ -0,0 +1,225 @@
+"""
+Low-dependency indexing utilities.
+"""
+import numpy as np
+
+from pandas.core.dtypes.common import is_list_like
+from pandas.core.dtypes.generic import ABCIndexClass, ABCSeries
+
+# -----------------------------------------------------------
+# Indexer Identification
+
+
+def is_list_like_indexer(key) -> bool:
+    """
+    Check if we have a list-like indexer that is *not* a NamedTuple.
+
+    Parameters
+    ----------
+    key : object
+
+    Returns
+    -------
+    bool
+    """
+    # allow a list_like, but exclude NamedTuples which can be indexers
+    return is_list_like(key) and not (isinstance(key, tuple) and type(key) is not tuple)
+
+
+def is_scalar_indexer(indexer, arr_value) -> bool:
+    # return True if we are all scalar indexers
+
+    if arr_value.ndim == 1:
+        if not isinstance(indexer, tuple):
+            indexer = tuple([indexer])
+            return any(isinstance(idx, np.ndarray) and len(idx) == 0 for idx in indexer)
+    return False
+
+
+def is_empty_indexer(indexer, arr_value) -> bool:
+    # return a boolean if we have an empty indexer
+
+    if is_list_like(indexer) and not len(indexer):
+        return True
+    if arr_value.ndim == 1:
+        if not isinstance(indexer, tuple):
+            indexer = tuple([indexer])
+        return any(isinstance(idx, np.ndarray) and len(idx) == 0 for idx in indexer)
+    return False
+
+
+# -----------------------------------------------------------
+# Indexer Validation
+
+
+def check_setitem_lengths(indexer, value, values) -> None:
+    """
+    Validate that value and indexer are the same length.
+
+    An special-case is allowed for when the indexer is a boolean array
+    and the number of true values equals the length of ``value``. In
+    this case, no exception is raised.
+
+    Parameters
+    ----------
+    indexer : sequence
+        The key for the setitem
+    value : array-like
+        The value for the setitem
+    values : array-like
+        The values being set into
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    ValueError
+        When the indexer is an ndarray or list and the lengths don't
+        match.
+    """
+    # boolean with truth values == len of the value is ok too
+    if isinstance(indexer, (np.ndarray, list)):
+        if is_list_like(value) and len(indexer) != len(value):
+            if not (
+                isinstance(indexer, np.ndarray)
+                and indexer.dtype == np.bool_
+                and len(indexer[indexer]) == len(value)
+            ):
+                raise ValueError(
+                    "cannot set using a list-like indexer "
+                    "with a different length than the value"
+                )
+
+    elif isinstance(indexer, slice):
+        # slice
+        if is_list_like(value) and len(values):
+            if len(value) != length_of_indexer(indexer, values):
+                raise ValueError(
+                    "cannot set using a slice indexer with a "
+                    "different length than the value"
+                )
+
+
+def validate_indices(indices: np.ndarray, n: int) -> None:
+    """
+    Perform bounds-checking for an indexer.
+
+    -1 is allowed for indicating missing values.
+
+    Parameters
+    ----------
+    indices : ndarray
+    n : int
+        length of the array being indexed
+
+    Raises
+    ------
+    ValueError
+
+    Examples
+    --------
+    >>> validate_indices([1, 2], 3)
+    # OK
+    >>> validate_indices([1, -2], 3)
+    ValueError
+    >>> validate_indices([1, 2, 3], 3)
+    IndexError
+    >>> validate_indices([-1, -1], 0)
+    # OK
+    >>> validate_indices([0, 1], 0)
+    IndexError
+    """
+    if len(indices):
+        min_idx = indices.min()
+        if min_idx < -1:
+            msg = "'indices' contains values less than allowed ({} < {})".format(
+                min_idx, -1
+            )
+            raise ValueError(msg)
+
+        max_idx = indices.max()
+        if max_idx >= n:
+            raise IndexError("indices are out-of-bounds")
+
+
+# -----------------------------------------------------------
+# Indexer Conversion
+
+
+def maybe_convert_indices(indices, n: int):
+    """
+    Attempt to convert indices into valid, positive indices.
+
+    If we have negative indices, translate to positive here.
+    If we have indices that are out-of-bounds, raise an IndexError.
+
+    Parameters
+    ----------
+    indices : array-like
+        The array of indices that we are to convert.
+    n : int
+        The number of elements in the array that we are indexing.
+
+    Returns
+    -------
+    valid_indices : array-like
+        An array-like of positive indices that correspond to the ones
+        that were passed in initially to this function.
+
+    Raises
+    ------
+    IndexError : one of the converted indices either exceeded the number
+        of elements (specified by `n`) OR was still negative.
+    """
+
+    if isinstance(indices, list):
+        indices = np.array(indices)
+        if len(indices) == 0:
+            # If list is empty, np.array will return float and cause indexing
+            # errors.
+            return np.empty(0, dtype=np.intp)
+
+    mask = indices < 0
+    if mask.any():
+        indices = indices.copy()
+        indices[mask] += n
+
+    mask = (indices >= n) | (indices < 0)
+    if mask.any():
+        raise IndexError("indices are out-of-bounds")
+    return indices
+
+
+# -----------------------------------------------------------
+# Unsorted
+
+
+def length_of_indexer(indexer, target=None) -> int:
+    """
+    return the length of a single non-tuple indexer which could be a slice
+    """
+    if target is not None and isinstance(indexer, slice):
+        target_len = len(target)
+        start = indexer.start
+        stop = indexer.stop
+        step = indexer.step
+        if start is None:
+            start = 0
+        elif start < 0:
+            start += target_len
+        if stop is None or stop > target_len:
+            stop = target_len
+        elif stop < 0:
+            stop += target_len
+        if step is None:
+            step = 1
+        elif step < 0:
+            step = -step
+        return (stop - start + step - 1) // step
+    elif isinstance(indexer, (ABCSeries, ABCIndexClass, np.ndarray, list)):
+        return len(indexer)
+    elif not is_list_like_indexer(indexer):
+        return 1
+    raise AssertionError("cannot find the length of the indexer")

pandas/core/indexes/base.py

@@ -66,6 +66,7 @@
 from pandas.core.arrays import ExtensionArray
 from pandas.core.base import IndexOpsMixin, PandasObject
 import pandas.core.common as com
+from pandas.core.indexers import maybe_convert_indices
 from pandas.core.indexes.frozen import FrozenList
 import pandas.core.missing as missing
 from pandas.core.ops import get_op_result_name, make_invalid_op
@@ -3318,7 +3319,6 @@ def _convert_list_indexer(self, keyarr, kind=None):
                 # values outside the range of indices so as to trigger an
                 # IndexError in maybe_convert_indices
                 indexer[indexer < 0] = len(self)
-                from pandas.core.indexing import maybe_convert_indices
 
                 return maybe_convert_indices(indexer, len(self))