DOC/API: expose ExtensionArray in public api (#20795)

Author: TomAugspurger

doc/source/api.rst

@@ -2549,6 +2549,8 @@ objects.
    api.extensions.register_dataframe_accessor
    api.extensions.register_series_accessor
    api.extensions.register_index_accessor
+   api.extensions.ExtensionDtype
+   api.extensions.ExtensionArray
 
 .. This is to prevent warnings in the doc build. We don't want to encourage
 .. these methods.

doc/source/extending.rst

@@ -61,7 +61,7 @@ Extension Types
 
 .. warning::
 
-   The ``ExtensionDtype`` and ``ExtensionArray`` APIs are new and
+   The :class:`pandas.api.extension.ExtensionDtype` and :class:`pandas.api.extension.ExtensionArray` APIs are new and
    experimental. They may change between versions without warning.
 
 Pandas defines an interface for implementing data types and arrays that *extend*
@@ -79,10 +79,10 @@ on :ref:`ecosystem.extensions`.
 
 The interface consists of two classes.
 
-``ExtensionDtype``
-^^^^^^^^^^^^^^^^^^
+:class:`~pandas.api.extension.ExtensionDtype`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-An ``ExtensionDtype`` is similar to a ``numpy.dtype`` object. It describes the
+A :class:`pandas.api.extension.ExtensionDtype` is similar to a ``numpy.dtype`` object. It describes the
 data type. Implementors are responsible for a few unique items like the name.
 
 One particularly important item is the ``type`` property. This should be the
@@ -91,8 +91,8 @@ extension array for IP Address data, this might be ``ipaddress.IPv4Address``.
 
 See the `extension dtype source`_ for interface definition.
 
-``ExtensionArray``
-^^^^^^^^^^^^^^^^^^
+:class:`~pandas.api.extension.ExtensionArray`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This class provides all the array-like functionality. ExtensionArrays are
 limited to 1 dimension. An ExtensionArray is linked to an ExtensionDtype via the

doc/source/whatsnew/v0.23.0.txt

@@ -365,7 +365,7 @@ for storing ip addresses.
       ...:
 
 ``IPArray`` isn't a normal 1-D NumPy array, but because it's a pandas
-``ExtensionArray``, it can be stored properly inside pandas' containers.
+:ref:`~pandas.api.extension.ExtensionArray, it can be stored properly inside pandas' containers.
 
 .. code-block:: ipython
 

pandas/api/extensions/__init__.py

@@ -2,3 +2,5 @@
 from pandas.core.accessor import (register_dataframe_accessor,  # noqa
                                   register_index_accessor,
                                   register_series_accessor)
+from pandas.core.arrays.base import ExtensionArray  # noqa
+from pandas.core.dtypes.dtypes import ExtensionDtype  # noqa

pandas/core/arrays/base.py

@@ -222,6 +222,7 @@ def dtype(self):
     @property
     def shape(self):
         # type: () -> Tuple[int, ...]
+        """Return a tuple of the array dimensions."""
         return (len(self),)
 
     @property

pandas/core/common.py

@@ -14,10 +14,9 @@
 from pandas.compat import long, zip, iteritems, PY36, OrderedDict
 from pandas.core.config import get_option
 from pandas.core.dtypes.generic import ABCSeries, ABCIndex
-from pandas.core.dtypes.common import _NS_DTYPE
+from pandas.core.dtypes.common import _NS_DTYPE, is_integer
 from pandas.core.dtypes.inference import _iterable_not_string
 from pandas.core.dtypes.missing import isna, isnull, notnull  # noqa
-from pandas.api import types
 from pandas.core.dtypes.cast import construct_1d_object_array_from_listlike
 
 
@@ -570,7 +569,7 @@ def _random_state(state=None):
     np.random.RandomState
     """
 
-    if types.is_integer(state):
+    if is_integer(state):
         return np.random.RandomState(state)
     elif isinstance(state, np.random.RandomState):
         return state