API: Public data attributes for EA-backed containers

This adds two new methods for working with EA-backed Series / Index.

- `.array -> Union[ExtensionArray, ndarray]`: the actual backing array
- `.to_numpy() -> ndarray`: A NumPy representation of the data

`.array` is always a reference to the actual data stored in the container.
Updating it inplace (not recommended) will be reflected in the Series (or
Index for that matter, so really not recommended).

`to_numpy()` may (or may not) require data copying / coercion.

Closes pandas-dev#19954

Author: TomAugspurger

pandas/core/base.py

@@ -765,6 +765,97 @@ def base(self):
                       FutureWarning, stacklevel=2)
         return self.values.base
 
+    @property
+    def array(self):
+        # type: () -> Union[np.ndarray, ExtensionArray]
+        """The actual Array backing this Series or Index.
+
+        Returns
+        -------
+        Union[ndarray, ExtensionArray]
+            This is the actual array stored within this object.
+
+        Notes
+        -----
+        This table lays out the different array types for each extension
+        dtype within pandas.
+
+        ================== =============================
+        dtype              array type
+        ================== =============================
+        category           Categorical
+        period             PeriodArray
+        interval           IntervalArray
+        IntegerNA          IntegerArray
+        datetime64[ns, tz] datetime64[ns]? DatetimeArray
+        ================== =============================
+
+        For any 3rd-party extension types, the array type will be an
+        ExtensionArray.
+
+        All remaining arrays (ndarrays), ``.array`` will be the ndarray
+        stored within.
+
+        See Also
+        --------
+        to_numpy : Similar method that always returns a NumPy array.
+
+        Examples
+        --------
+        >>> ser = pd.Series(pd.Categorical(['a', 'b', 'a']))
+        >>> ser.array
+        [a, b, a]
+        Categories (2, object): [a, b]
+        """
+        return self._values
+
+    def to_numpy(self):
+        """A NumPy array representing the values in this Series or Index.
+
+        The returned array will be the same up to equality (values equal
+        in `self` will be equal in the returned array; likewise for values
+        that are not equal).
+
+        Returns
+        -------
+        numpy.ndarray
+            An ndarray with
+
+        Notes
+        -----
+        For NumPy arrays, this will be a reference to the actual data stored
+        in this Series or Index.
+
+        For extension types, this may involve copying data and coercing the
+        result to a NumPy type (possibly object), which may be expensive.
+
+        This table lays out the different array types for each extension
+        dtype within pandas.
+
+        ================== ================================
+        dtype              array type
+        ================== ================================
+        category[T]        ndarray[T] (same dtype as input)
+        period             ndarray[object] (Periods)
+        interval           ndarray[object] (Intervals)
+        IntegerNA          IntegerArray[object]
+        datetime64[ns, tz] datetime64[ns]? object?
+        ================== ================================
+
+        See Also
+        --------
+        array : Get the actual data stored within.
+
+        Examples
+        --------
+        >>> ser = pd.Series(pd.Categorical(['a', 'b', 'a']))
+        >>> ser.to_numpy()
+        array(['a', 'b', 'a'], dtype=object)
+        """
+        if is_extension_array_dtype(self.dtype):
+            return np.asarray(self._values)
+        return self._values
+
     @property
     def _ndarray_values(self):
         # type: () -> np.ndarray

pandas/core/indexes/base.py

@@ -710,6 +710,7 @@ def values(self):
     @property
     def _values(self):
         # type: () -> Union[ExtensionArray, Index]
+        # TODO: remove in favor of .array
         # TODO(EA): remove index types as they become extension arrays
         """The best array representation.
 
@@ -739,7 +740,7 @@ def _values(self):
         values
         _ndarray_values
         """
-        return self.values
+        return self._data
 
     def get_values(self):
         """

pandas/core/indexes/multi.py

@@ -288,6 +288,26 @@ def _verify_integrity(self, labels=None, levels=None):
     def levels(self):
         return self._levels
 
+    @property
+    def _values(self):
+        # TODO: remove
+        # We override here, since our parent uses _data, which we dont' use.
+        return self.values
+
+    @property
+    def array(self):
+        """
+        Raises a ValueError for `MultiIndex` because there's no single
+        array backing a MultiIndex.
+
+        Raises
+        ------
+        ValueError
+        """
+        msg = ("MultiIndex has no single backing array. Use "
+               "'MultiIndex.to_numpy()' to get a NumPy array of tuples.")
+        raise ValueError(msg)
+
     @property
     def _is_homogeneous_type(self):
         """Whether the levels of a MultiIndex all have the same dtype.

pandas/tests/test_base.py

@@ -1243,3 +1243,54 @@ def test_ndarray_values(array, expected):
     r_values = pd.Index(array)._ndarray_values
     tm.assert_numpy_array_equal(l_values, r_values)
     tm.assert_numpy_array_equal(l_values, expected)
+
+
+@pytest.mark.parametrize("array, attr", [
+    (np.array([1, 2], dtype=np.int64), None),
+    (pd.Categorical(['a', 'b']), '_codes'),
+    (pd.core.arrays.period_array(['2000', '2001'], freq='D'), '_data'),
+    (pd.core.arrays.integer_array([0, np.nan]), '_data'),
+    (pd.core.arrays.IntervalArray.from_breaks([0, 1]), '_left'),
+    (pd.SparseArray([0, 1]), '_sparse_values'),
+    # TODO: DatetimeArray(add)
+])
+@pytest.mark.parametrize('box', [pd.Series, pd.Index])
+def test_array(array, attr, box):
+    if array.dtype.name in ('Int64', 'Sparse[int64, 0]'):
+        pytest.skip("No index type for {}".format(array.dtype))
+    result = box(array, copy=False).array
+
+    if attr:
+        array = getattr(array, attr)
+        result = getattr(result, attr)
+
+    assert result is array
+
+
+def test_array_multiindex_raises():
+    idx = pd.MultiIndex.from_product([['A'], ['a', 'b']])
+    with tm.assert_raises_regex(ValueError, 'MultiIndex'):
+        idx.array
+
+
+@pytest.mark.parametrize('array, expected', [
+    (np.array([1, 2], dtype=np.int64), np.array([1, 2], dtype=np.int64)),
+    (pd.Categorical(['a', 'b']), np.array(['a', 'b'], dtype=object)),
+    (pd.core.arrays.period_array(['2000', '2001'], freq='D'),
+     np.array([pd.Period('2000', freq="D"), pd.Period('2001', freq='D')])),
+    (pd.core.arrays.integer_array([0, np.nan]),
+     np.array([1, np.nan], dtype=object)),
+    (pd.core.arrays.IntervalArray.from_breaks([0, 1, 2]),
+     np.array([pd.Interval(0, 1), pd.Interval(1, 2)], dtype=object)),
+    (pd.SparseArray([0, 1]), np.array([0, 1], dtype=np.int64)),
+    # TODO: DatetimeArray(add)
+])
+@pytest.mark.parametrize('box', [pd.Series, pd.Index])
+def test_to_numpy(array, expected, box):
+    thing = box(array)
+
+    if array.dtype.name in ('Int64', 'Sparse[int64, 0]'):
+        pytest.skip("No index type for {}".format(array.dtype))
+
+    result = thing.to_numpy()
+    tm.assert_numpy_array_equal(result, expected)