DOC/TST: Indexing with NA raises

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
         language: python_venv
         additional_dependencies: [flake8-comprehensions>=3.1.0]
 -   repo: https://github.com/pre-commit/mirrors-isort
-    rev: v4.3.20
+    rev: v4.3.21
     hooks:
     -   id: isort
         language: python_venv

doc/source/reference/extensions.rst

@@ -18,8 +18,6 @@ objects.
    api.extensions.register_series_accessor
    api.extensions.register_index_accessor
    api.extensions.ExtensionDtype
-   api.extensions.is_bool_indexer
-   api.extensions.check_bool_array_indexer
 
 .. autosummary::
    :toctree: api/
@@ -28,7 +26,6 @@ objects.
    api.extensions.ExtensionArray
    arrays.PandasArray
 
-
 .. We need this autosummary so that methods and attributes are generated.
 .. Separate block, since they aren't classes.
 
@@ -62,3 +59,11 @@ objects.
       api.extensions.ExtensionArray.nbytes
       api.extensions.ExtensionArray.ndim
       api.extensions.ExtensionArray.shape
+
+Additionally, we have some utility methods for ensuring your object
+behaves correctly.
+
+.. autosummary::
+  :toctree: api/
+
+  api.indexers.check_bool_array_indexer

pandas/api/extensions/__init__.py

@@ -11,5 +11,3 @@
 )
 from pandas.core.algorithms import take  # noqa: F401
 from pandas.core.arrays import ExtensionArray, ExtensionScalarOpsMixin  # noqa: F401
-from pandas.core.common import is_bool_indexer  # noqa: F401
-from pandas.core.indexing import check_bool_array_indexer  # noqa: F401

pandas/api/indexers/__init__.py

@@ -1,2 +1,3 @@
 """Public API for Rolling Window Indexers"""
+from pandas.core.indexers import check_bool_array_indexer  # noqa: F401
 from pandas.core.window.indexers import BaseIndexer  # noqa: F401

pandas/core/arrays/boolean.py

@@ -29,7 +29,8 @@
 from pandas.core import nanops, ops
 from pandas.core.algorithms import take
 from pandas.core.arrays import ExtensionArray, ExtensionOpsMixin
-from pandas.core.common import is_bool_indexer
+import pandas.core.common as com
+from pandas.core.indexers import check_bool_array_indexer
 
 if TYPE_CHECKING:
     from pandas._typing import Scalar
@@ -316,15 +317,12 @@ def _hasna(self) -> bool:
         return self._mask.any()
 
     def __getitem__(self, item):
-        # import here to avoid circular import. Probably need to restructure
-        from pandas.core.indexing import check_bool_array_indexer
-
         if is_integer(item):
             if self._mask[item]:
                 return self.dtype.na_value
             return self._data[item]
 
-        elif is_bool_indexer(item):
+        elif com.is_bool_indexer(item):
             item = check_bool_array_indexer(self, item)
 
         return type(self)(self._data[item], self._mask[item])

pandas/core/arrays/categorical.py

@@ -49,6 +49,7 @@
 from pandas.core.base import NoNewAttributesMixin, PandasObject, _shared_docs
 import pandas.core.common as com
 from pandas.core.construction import array, extract_array, sanitize_array
+from pandas.core.indexers import check_bool_array_indexer
 from pandas.core.missing import interpolate_2d
 from pandas.core.ops.common import unpack_zerodim_and_defer
 from pandas.core.sorting import nargsort
@@ -1990,8 +1991,6 @@ def __getitem__(self, key):
         """
         Return an item.
         """
-        from pandas.core.indexing import check_bool_array_indexer
-
         if isinstance(key, (int, np.integer)):
             i = self._codes[key]
             if i == -1:

pandas/core/arrays/datetimelike.py

@@ -40,6 +40,7 @@
 from pandas.core import missing, nanops
 from pandas.core.algorithms import checked_add_with_arr, take, unique1d, value_counts
 import pandas.core.common as com
+from pandas.core.indexers import check_bool_array_indexer
 from pandas.core.ops.common import unpack_zerodim_and_defer
 from pandas.core.ops.invalid import make_invalid_op
 
@@ -436,8 +437,6 @@ def __getitem__(self, key):
             return type(self)(val, dtype=self.dtype)
 
         if com.is_bool_indexer(key):
-            from pandas.core.indexing import check_bool_array_indexer
-
             key = check_bool_array_indexer(self, key)
             if key.all():
                 key = slice(0, None, None)

pandas/core/arrays/integer.py

@@ -26,7 +26,8 @@
 from pandas.core import nanops, ops
 from pandas.core.algorithms import take
 from pandas.core.arrays import ExtensionArray, ExtensionOpsMixin
-from pandas.core.common import is_bool_indexer
+import pandas.core.common as com
+from pandas.core.indexers import check_bool_array_indexer
 from pandas.core.ops import invalid_comparison
 from pandas.core.ops.common import unpack_zerodim_and_defer
 from pandas.core.tools.numeric import to_numeric
@@ -365,15 +366,12 @@ def _from_factorized(cls, values, original):
         return integer_array(values, dtype=original.dtype)
 
     def __getitem__(self, item):
-        # Importing this at the top-level causes many unrelated(?) mypy failures
-        from pandas.core.indexing import check_bool_array_indexer
-
         if is_integer(item):
             if self._mask[item]:
                 return self.dtype.na_value
             return self._data[item]
 
-        elif is_bool_indexer(item):
+        elif com.is_bool_indexer(item):
             item = check_bool_array_indexer(self, item)
 
         return type(self)(self._data[item], self._mask[item])

pandas/core/arrays/numpy_.py

@@ -17,8 +17,9 @@
 from pandas import compat
 from pandas.core import nanops
 from pandas.core.algorithms import searchsorted, take, unique
-from pandas.core.common import is_bool_indexer
+import pandas.core.common as com
 from pandas.core.construction import extract_array
+from pandas.core.indexers import check_bool_array_indexer
 from pandas.core.missing import backfill_1d, pad_1d
 
 from .base import ExtensionArray, ExtensionOpsMixin
@@ -232,13 +233,10 @@ def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
     # Pandas ExtensionArray Interface
 
     def __getitem__(self, item):
-        # Avoid mypy failures when importing at the top-level
-        from pandas.core.indexing import check_bool_array_indexer
-
         if isinstance(item, type(self)):
             item = item._ndarray
 
-        elif is_bool_indexer(item):
+        elif com.is_bool_indexer(item):
             item = check_bool_array_indexer(self, item)
 
         result = self._ndarray[item]

pandas/core/common.py

@@ -121,10 +121,10 @@ def is_bool_indexer(key: Any) -> bool:
 
     See Also
     --------
-    api.extensions.check_bool_array_indexer : Check that `key`
-        is a valid mask for an array, and convert to an ndarary.
+    check_bool_array_indexer : Check that `key`
+        is a valid mask for an array, and convert to an ndarray.
     """
-    na_msg = "cannot index with vector containing NA / NaN values"
+    na_msg = "cannot mask with array containing NA / NaN values"
     if isinstance(key, (ABCSeries, np.ndarray, ABCIndex)) or (
         is_array_like(key) and is_extension_array_dtype(key.dtype)
     ):

pandas/core/indexers.py

@@ -3,6 +3,8 @@
 """
 import numpy as np
 
+from pandas._typing import AnyArrayLike
+
 from pandas.core.dtypes.common import is_list_like
 from pandas.core.dtypes.generic import ABCIndexClass, ABCSeries
 
@@ -240,3 +242,68 @@ def length_of_indexer(indexer, target=None) -> int:
     elif not is_list_like_indexer(indexer):
         return 1
     raise AssertionError("cannot find the length of the indexer")
+
+
+def check_bool_array_indexer(array: AnyArrayLike, mask: AnyArrayLike) -> np.ndarray:
+    """
+    Check if `mask` is a valid boolean indexer for `array`.
+
+    `array` and `mask` are checked to have the same length, and the
+    dtype is validated.
+
+    .. versionadded:: 1.0.0
+
+    Parameters
+    ----------
+    array : array
+        The array that's being masked.
+    mask : array
+        The boolean array that's masking.
+
+    Returns
+    -------
+    numpy.ndarray
+        The validated boolean mask.
+
+    Raises
+    ------
+    IndexError
+        When the lengths don't match.
+    ValueError
+        When `mask` cannot be converted to a bool-dtype ndarray.
+
+    See Also
+    --------
+    api.extensions.is_bool_indexer : Check if `key` is a boolean indexer.
+
+    Examples
+    --------
+    A boolean ndarray is returned when the arguments are all valid.
+
+    >>> mask = pd.array([True, False])
+    >>> arr = pd.Series([1, 2])
+    >>> pd.api.extensions.check_bool_array_indexer(arr, mask)
+    array([ True, False])
+
+    An IndexError is raised when the lengths don't match.
+
+    >>> mask = pd.array([True, False, True])
+    >>> pd.api.extensions.check_bool_array_indexer(arr, mask)
+    Traceback (most recent call last):
+    ...
+    IndexError: Item wrong length 3 instead of 2.
+
+    A ValueError is raised when the mask cannot be converted to
+    a bool-dtype ndarray.
+
+    >>> mask = pd.array([True, pd.NA])
+    >>> pd.api.extensions.check_bool_array_indexer(arr, mask)
+    Traceback (most recent call last):
+    ...
+    ValueError: cannot convert to bool numpy array in presence of missing values
+    """
+    result = np.asarray(mask, dtype=bool)
+    # GH26658
+    if len(result) != len(array):
+        raise IndexError(f"Item wrong length {len(result)} instead of {len(array)}.")
+    return result

pandas/core/indexing.py

@@ -21,9 +21,12 @@
 from pandas.core.dtypes.generic import ABCDataFrame, ABCMultiIndex, ABCSeries
 from pandas.core.dtypes.missing import _infer_fill_value, isna
 
-from pandas._typing import AnyArrayLike
 import pandas.core.common as com
-from pandas.core.indexers import is_list_like_indexer, length_of_indexer
+from pandas.core.indexers import (
+    check_bool_array_indexer,
+    is_list_like_indexer,
+    length_of_indexer,
+)
 from pandas.core.indexes.api import Index, InvalidIndexError
 
 
@@ -2270,69 +2273,6 @@ def convert_to_index_sliceable(obj, key):
     return None
 
 
-def check_bool_array_indexer(array: AnyArrayLike, mask: AnyArrayLike) -> np.ndarray:
-    """
-    Check if `mask` is a valid boolean indexer for `array`.
-
-    `array` and `mask` are checked to have the same length, and the
-    dtype is validated.
-
-    Parameters
-    ----------
-    array : array
-        The array that's being masked.
-    mask : array
-        The boolean array that's masking.
-
-    Returns
-    -------
-    numpy.ndarray
-        The validated boolean mask.
-
-    Raises
-    ------
-    IndexError
-        When the lengths don't match.
-    ValueError
-        When `mask` cannot be converted to a bool-dtype ndarray.
-
-    See Also
-    --------
-    api.extensions.is_bool_indexer : Check if `key` is a boolean indexer.
-
-    Examples
-    --------
-    A boolean ndarray is returned when the arguments are all valid.
-
-    >>> mask = pd.array([True, False])
-    >>> arr = pd.Series([1, 2])
-    >>> pd.api.extensions.check_bool_array_indexer(arr, mask)
-    array([ True, False])
-
-    An IndexError is raised when the lengths don't match.
-
-    >>> mask = pd.array([True, False, True])
-    >>> pd.api.extensions.check_bool_array_indexer(arr, mask)
-    Traceback (most recent call last):
-    ...
-    IndexError: Item wrong length 3 instead of 2.
-
-    A ValueError is raised when the mask cannot be converted to
-    a bool-dtype ndarray.
-
-    >>> mask = pd.array([True, pd.NA])
-    >>> pd.api.extensions.check_bool_array_indexer(arr, mask)
-    Traceback (most recent call last):
-    ...
-    ValueError: cannot convert to bool numpy array in presence of missing values
-    """
-    result = np.asarray(mask, dtype=bool)
-    # GH26658
-    if len(result) != len(array):
-        raise IndexError(f"Item wrong length {len(result)} instead of {len(array)}.")
-    return result
-
-
 def check_bool_indexer(index: Index, key) -> np.ndarray:
     """
     Check if key is a valid boolean indexer for an object with such index and

pandas/tests/extension/base/getitem.py

@@ -130,7 +130,7 @@ def test_getitem_mask_raises(self, data):
         with pytest.raises(IndexError):
             data[mask]
 
-    def test_getitem_boolenarray_mask(self, data):
+    def test_getitem_boolean_array_mask(self, data):
         mask = pd.array(np.zeros(data.shape, dtype="bool"), dtype="boolean")
         result = data[mask]
         assert len(result) == 0
@@ -149,7 +149,7 @@ def test_getitem_boolenarray_mask(self, data):
         result = pd.Series(data)[mask]
         self.assert_series_equal(result, expected)
 
-    def test_getitem_boolenarray_mask_raises(self, data):
+    def test_getitem_boolean_array_mask_raises(self, data):
         mask = pd.array(np.zeros(data.shape, dtype="bool"), dtype="boolean")
         mask[:2] = pd.NA
         with pytest.raises(ValueError):

pandas/tests/extension/decimal/array.py

@@ -8,11 +8,7 @@
 from pandas.core.dtypes.base import ExtensionDtype
 
 import pandas as pd
-from pandas.api.extensions import (
-    check_bool_array_indexer,
-    is_bool_indexer,
-    register_extension_dtype,
-)
+from pandas.api.extensions import register_extension_dtype
 from pandas.core.arrays import ExtensionArray, ExtensionScalarOpsMixin
 
 
@@ -113,8 +109,15 @@ def __getitem__(self, item):
         if isinstance(item, numbers.Integral):
             return self._data[item]
         else:
-            if is_bool_indexer(item):
-                item = check_bool_array_indexer(self, item)
+            # array, slice.
+            if pd.api.types.is_list_like(item):
+                if not pd.api.types.is_array_like(item):
+                    item = pd.array(item)
+                dtype = item.dtype
+                if pd.api.types.is_bool_dtype(dtype):
+                    item = pd.api.indexers.check_bool_array_indexer(self, item)
+                elif pd.api.types.is_integer_dtype(dtype):
+                    item = np.asarray(item, dtype="int")
             return type(self)(self._data[item])
 
     def take(self, indexer, allow_fill=False, fill_value=None):