ENH: add NDArrayBackedExtensionArray to public API

doc/source/development/extending.rst

@@ -135,6 +135,110 @@ by some other storage type, like Python lists.
 See the `extension array source`_ for the interface definition. The docstrings
 and comments contain guidance for properly implementing the interface.
 
+:class:`~pandas.api.extensions.NDArrayBackedExtensionArray`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For ExtensionArrays backed by a single NumPy array, the
+:class:`~pandas.api.extensions.NDArrayBackedExtensionArray` class can save you
+some effort. It contains a private property ``_ndarray`` with the backing NumPy
+array and implements the extension array interface.
+
+Implement the following:
+
+``_box_func``
+  Convert from array values to the type you wish to expose to users.
+
+``_internal_fill_value``
+   Scalar used to denote ``NA`` value inside our ``self._ndarray``, e.g. ``-1``
+   for ``Categorical``, ``iNaT`` for ``Period``.
+
+``_validate_scalar``
+  Convert from an object to a value which can be stored in the NumPy array.
+
+``_validate_setitem_value``
+  Convert a value or values for use in setting a value or values in the backing
+  NumPy array.
+
+``_validate_searchsorted_value``
+  Convert a value for use in searching for a value in the backing NumPy array.
+  Note: in most cases, the implementation can be identical to that of
+  ``_validate_setitem_value``.
+
+.. code-block:: python
+
+    class DateArray(NDArrayBackedExtensionArray):
+        _internal_fill_value = numpy.datetime64("NaT")
+
+        def __init__(self, values):
+            backing_array_dtype = "<M8[ns]"
+            super().__init__(values=values, dtype=backing_array_dtype)
+
+        def _box_func(self, value):
+            if pandas.isna(x):
+                return pandas.NaT
+            return x.astype("datetime64[us]").item().date()
+
+        def _validate_scalar(self, scalar):
+            if pandas.isna(scalar):
+                return numpy.datetime64("NaT")
+            elif isinstance(scalar, datetime.date):
+                return pandas.Timestamp(
+                    year=scalar.year, month=scalar.month, day=scalar.day
+                ).to_datetime64()
+            else:
+                raise TypeError("Invalid value type", scalar)
+
+        def _validate_setitem_value(self, value):
+            if pandas.api.types.is_list_like(value):
+                return [self._validate_scalar(v) for v in value]
+            return self._validate_scalar(value)
+
+        def _validate_searchsorted_value(self, value):
+            return self._validate_setitem_value(value)
+
+
+To support 2D arrays, use the ``_from_backing_data`` helper function when a
+method is called on multi-dimensional data of the same dtype as ``_ndarray``.
+
+.. code-block:: python
+
+    class CustomArray(NDArrayBackedExtensionArray):
+
+        ...
+
+        def min(self, *, axis: Optional[int] = None, skipna: bool = True, **kwargs):
+            pandas.compat.numpy.function.validate_minnumpy_validate_min((), kwargs)
+            result = pandas.core.nanops.nanmin(
+                values=self._ndarray, axis=axis, mask=self.isna(), skipna=skipna
+            )
+            if axis is None or self.ndim == 1:
+                return self._box_func(result)
+            return self._from_backing_data(result)
+
+
+Subclass the tests in :mod:`pandas.tests.extension.base` in your test suite to
+validate your implementation.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def data():
+        return CustomArray(numpy.arange(-10, 10, 1)
+
+
+    class Test2DCompat(base.NDArrayBacked2DTests):
+        pass
+
+
+    class TestComparisonOps(base.BaseComparisonOpsTests):
+        pass
+
+    ...
+
+    class TestSetitem(base.BaseSetitemTests):
+        pass
+
+
 .. _extending.extension.operator:
 
 :class:`~pandas.api.extensions.ExtensionArray` operator support

doc/source/reference/extensions.rst

@@ -24,6 +24,7 @@ objects.
    :template: autosummary/class_without_autosummary.rst
 
    api.extensions.ExtensionArray
+   api.extensions.NDArrayBackedExtensionArray
    arrays.PandasArray
 
 .. We need this autosummary so that methods and attributes are generated.
@@ -62,6 +63,26 @@ objects.
       api.extensions.ExtensionArray.ndim
       api.extensions.ExtensionArray.shape
       api.extensions.ExtensionArray.tolist
+      api.extensions.NDArrayBackedExtensionArray.dtype
+      api.extensions.NDArrayBackedExtensionArray.argmax
+      api.extensions.NDArrayBackedExtensionArray.argmin
+      api.extensions.NDArrayBackedExtensionArray.argsort
+      api.extensions.NDArrayBackedExtensionArray.astype
+      api.extensions.NDArrayBackedExtensionArray.dropna
+      api.extensions.NDArrayBackedExtensionArray.equals
+      api.extensions.NDArrayBackedExtensionArray.factorize
+      api.extensions.NDArrayBackedExtensionArray.fillna
+      api.extensions.NDArrayBackedExtensionArray.insert
+      api.extensions.NDArrayBackedExtensionArray.isin
+      api.extensions.NDArrayBackedExtensionArray.isna
+      api.extensions.NDArrayBackedExtensionArray.searchsorted
+      api.extensions.NDArrayBackedExtensionArray.shift
+      api.extensions.NDArrayBackedExtensionArray.take
+      api.extensions.NDArrayBackedExtensionArray.to_numpy
+      api.extensions.NDArrayBackedExtensionArray.tolist
+      api.extensions.NDArrayBackedExtensionArray.unique
+      api.extensions.NDArrayBackedExtensionArray.value_counts
+      api.extensions.NDArrayBackedExtensionArray.view
 
 Additionally, we have some utility methods for ensuring your object
 behaves correctly.

doc/source/whatsnew/v2.0.0.rst

@@ -65,6 +65,7 @@ Other enhancements
 - :func:`timedelta_range` now supports a ``unit`` keyword ("s", "ms", "us", or "ns") to specify the desired resolution of the output index (:issue:`49824`)
 - :meth:`DataFrame.to_json` now supports a ``mode`` keyword with supported inputs 'w' and 'a'. Defaulting to 'w', 'a' can be used when lines=True and orient='records' to append record oriented json lines to an existing json file. (:issue:`35849`)
 - Added ``name`` parameter to :meth:`IntervalIndex.from_breaks`, :meth:`IntervalIndex.from_arrays` and :meth:`IntervalIndex.from_tuples` (:issue:`48911`)
+- :class:`NDArrayBackedExtensionArray` now exposed in the public API. (:issue:`45544`)
 -
 
 .. ---------------------------------------------------------------------------

pandas/api/extensions/__init__.py

@@ -18,6 +18,7 @@
 from pandas.core.arrays import (
     ExtensionArray,
     ExtensionScalarOpsMixin,
+    NDArrayBackedExtensionArray,
 )
 
 __all__ = [
@@ -30,4 +31,5 @@
     "take",
     "ExtensionArray",
     "ExtensionScalarOpsMixin",
+    "NDArrayBackedExtensionArray",
 ]

pandas/core/arrays/__init__.py

@@ -1,3 +1,4 @@
+from pandas.core.arrays._mixins import NDArrayBackedExtensionArray
 from pandas.core.arrays.arrow import ArrowExtensionArray
 from pandas.core.arrays.base import (
     ExtensionArray,
@@ -34,6 +35,7 @@
     "FloatingArray",
     "IntegerArray",
     "IntervalArray",
+    "NDArrayBackedExtensionArray",
     "PandasArray",
     "PeriodArray",
     "period_array",

pandas/core/arrays/_mixins.py

@@ -119,6 +119,7 @@ def _validate_scalar(self, value):
 
     # ------------------------------------------------------------------------
 
+    @doc(ExtensionArray.view)
     def view(self, dtype: Dtype | None = None) -> ArrayLike:
         # We handle datetime64, datetime64tz, timedelta64, and period
         #  dtypes here. Everything else we pass through to the underlying
@@ -152,6 +153,7 @@ def view(self, dtype: Dtype | None = None) -> ArrayLike:
         # Sequence[int]]], List[Any], _DTypeDict, Tuple[Any, Any]]]"
         return arr.view(dtype=dtype)  # type: ignore[arg-type]
 
+    @doc(ExtensionArray.view)
     def take(
         self: NDArrayBackedExtensionArrayT,
         indices: TakeIndexer,
@@ -388,8 +390,9 @@ def insert(
         self: NDArrayBackedExtensionArrayT, loc: int, item
     ) -> NDArrayBackedExtensionArrayT:
         """
-        Make new ExtensionArray inserting new item at location. Follows
-        Python list.append semantics for negative values.
+        Make new ExtensionArray inserting new item at location.
+
+        Follows Python list.append semantics for negative values.
 
         Parameters
         ----------

pandas/tests/api/test_api.py

@@ -5,6 +5,7 @@
 import pandas as pd
 from pandas import api
 import pandas._testing as tm
+from pandas.api import extensions
 
 
 class Base:
@@ -241,6 +242,33 @@ def test_api(self):
         self.check(api, self.allowed)
 
 
+class TestExtensions(Base):
+    # top-level classes
+    classes = [
+        "ExtensionDtype",
+        "ExtensionArray",
+        "ExtensionScalarOpsMixin",
+        "NDArrayBackedExtensionArray",
+    ]
+
+    # top-level functions
+    funcs = [
+        "register_extension_dtype",
+        "register_dataframe_accessor",
+        "register_index_accessor",
+        "register_series_accessor",
+        "take",
+    ]
+
+    # misc
+    misc = ["no_default"]
+
+    def test_api(self):
+        checkthese = self.classes + self.funcs + self.misc
+
+        self.check(namespace=extensions, expected=checkthese)
+
+
 class TestTesting(Base):
     funcs = [
         "assert_frame_equal",