API: added array

doc/source/api.rst

@@ -702,6 +702,19 @@ strings and apply several methods to it. These can be accessed like
        Series.dt
        Index.str
 
+
+.. _api.arrays:
+
+Arrays
+------
+
+Pandas and third-party libraries can extend NumPy's type system (see :ref:`extending.extension-types`).
+
+.. autosummary::
+   :toctree: generated/
+
+   array
+
 .. _api.categorical:
 
 Categorical
@@ -790,6 +803,56 @@ following usable methods and properties:
    Series.cat.as_ordered
    Series.cat.as_unordered
 
+.. _api.arrays.integerna:
+
+Integer-NA
+~~~~~~~~~~
+
+:class:`arrays.IntegerArray` can hold integer data, potentially with missing
+values.
+
+.. autosummary::
+   :toctree: generated/
+
+   IntegerArray
+
+.. _api.arrays.interval:
+
+Interval
+~~~~~~~~
+
+:class:`IntervalArray` is an array for storing data representing intervals.
+The scalar type is a :class:`Interval`. These may be stored in a :class:`Series`
+or as a :class:`IntervalIndex`. :class:`IntervalArray` can be closed on the
+left, right, or both, or neither sides.
+
+.. currentmodule:: pandas
+
+.. autosummary::
+   :toctree: generated/
+
+   IntervalArray
+
+.. _api.arrays.period:
+
+Period
+~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   PeriodArray
+
+Sparse
+~~~~~~
+
+.. _api.arrays.sparse:
+
+.. autosummary::
+   :toctree: generated/
+
+   SparseArray
+
 Plotting
 ~~~~~~~~
 
@@ -1675,6 +1738,7 @@ IntervalIndex Components
    IntervalIndex.get_indexer
    IntervalIndex.set_closed
    IntervalIndex.overlaps
+   IntervalArray.to_tuples
 
 
 .. _api.multiindex:
@@ -1905,6 +1969,8 @@ Methods
     PeriodIndex.strftime
     PeriodIndex.to_timestamp
 
+.. api.scalars:
+
 Scalars
 -------
 

doc/source/whatsnew/v0.24.0.txt

@@ -101,6 +101,18 @@ Reduction and groupby operations such as 'sum' work.
 
    The Integer NA support currently uses the captilized dtype version, e.g. ``Int8`` as compared to the traditional ``int8``. This may be changed at a future date.
 
+.. _whatsnew_0240.enhancements.array:
+
+A new top-level method :func:`array` has been added for creating arrays (:issue:`22860`).
+This can be used to create NumPy arrays, or any :ref:`extension array <extending.extension-types>`, including
+extension arrays registered by :ref:`3rd party libraries <ecosystem.extensions>`.
+
+.. ipython:: python
+
+   pd.array([1, 2, np.nan], dtype='Int64')
+   pd.array(['a', 'b', 'c'], dtype='category')
+   pd.array([1, 2])
+
 .. _whatsnew_0240.enhancements.read_html:
 
 ``read_html`` Enhancements

pandas/arrays/__init__.py

@@ -0,0 +1,17 @@
+"""
+All of pandas' ExtensionArrays and ExtensionDtypes.
+
+See :ref:`extending.extension-types` for more.
+"""
+from pandas.core.arrays import (
+    IntervalArray, PeriodArray, Categorical, SparseArray, IntegerArray,
+)
+
+
+__all__ = [
+    'Categorical',
+    'IntegerArray',
+    'IntervalArray',
+    'PeriodArray',
+    'SparseArray',
+]

pandas/core/api.py

@@ -4,9 +4,26 @@
 
 import numpy as np
 
+from pandas.core.arrays import IntervalArray
+from pandas.core.arrays.integer import (
+    Int8Dtype,
+    Int16Dtype,
+    Int32Dtype,
+    Int64Dtype,
+    UInt8Dtype,
+    UInt16Dtype,
+    UInt32Dtype,
+    UInt64Dtype,
+)
 from pandas.core.algorithms import factorize, unique, value_counts
 from pandas.core.dtypes.missing import isna, isnull, notna, notnull
-from pandas.core.arrays import Categorical
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    PeriodDtype,
+    IntervalDtype,
+    DatetimeTZDtype,
+)
+from pandas.core.arrays import Categorical, array
 from pandas.core.groupby import Grouper
 from pandas.io.formats.format import set_eng_float_format
 from pandas.core.index import (Index, CategoricalIndex, Int64Index,

pandas/core/arrays/__init__.py

@@ -1,3 +1,4 @@
+from .array_ import array  # noqa
 from .base import (ExtensionArray,    # noqa
                    ExtensionOpsMixin,
                    ExtensionScalarOpsMixin)

pandas/core/arrays/array_.py

@@ -0,0 +1,84 @@
+import numpy as np
+
+from pandas._libs import lib, tslibs
+
+from pandas.core.dtypes.common import is_extension_array_dtype
+from pandas.core.dtypes.dtypes import registry
+from pandas.core.dtypes.generic import ABCIndexClass, ABCSeries
+
+
+def array(data, dtype=None, copy=False):
+    """
+    Create an array.
+
+    Parameters
+    ----------
+    data : Sequence[object]
+        A sequence of scalar instances for `dtype`. The underlying
+        array will be extracted from a Series or Index object.
+
+    dtype : Union[str, np.dtype, ExtensionDtype], optional
+        The dtype to use for the array. This may be a NumPy
+        dtype, or an extension type registered with pandas using
+        :meth:`pandas.api.extensions.register_extension_dtype`.
+
+        By default, the dtype will be inferred from the data
+        with :meth:`numpy.array`.
+
+    copy : bool, default False
+        Whether to copy the data.
+
+    Returns
+    -------
+    Array : Union[ndarray, ExtensionArray]
+
+    Examples
+    --------
+    If a dtype is not specified, `data` is passed through to
+    :meth:`numpy.array`, and an ndarray is returned.
+
+    >>> pd.array([1, 2])
+    array([1, 2])
+
+    Or the NumPy dtype can be specified
+
+    >>> pd.array([1, 2], dtype=np.int32)
+    array([1, 2], dtype=int32)
+
+    You can use the string alias for `dtype`
+
+    >>> pd.array(['a', 'b', 'a'], dtype='category')
+    [a, b, a]
+    Categories (2, object): [a, b]
+
+    Or specify the actual dtype
+
+    >>> pd.array(['a', 'b', 'a'],
+    ...          dtype=pd.CategoricalDtype(['a', 'b', 'c'], ordered=True))
+    [a, b, a]
+    Categories (3, object): [a < b < c]
+    """
+    from pandas.core.arrays import period_array
+
+    if isinstance(data, (ABCSeries, ABCIndexClass)):
+        data = data._values
+
+    # this returns None for not-found dtypes.
+    dtype = registry.find(dtype) or dtype
+
+    if is_extension_array_dtype(dtype):
+        cls = dtype.construct_array_type()
+        return cls._from_sequence(data, dtype=dtype, copy=copy)
+
+    if dtype is None:
+        inferred_dtype = lib.infer_dtype(data)
+        if inferred_dtype == 'period':
+            try:
+                return period_array(data)
+            except tslibs.IncompatibleFrequency:
+                pass  # we return an array below.
+
+        # TODO(DatetimeArray): handle this type
+        # TODO(BooleanArray): handle this type
+
+    return np.array(data, dtype=dtype, copy=copy)

pandas/core/arrays/interval.py

@@ -81,7 +81,9 @@
 from_arrays
 from_tuples
 from_breaks
+overlaps
 set_closed
+to_tuples
 %(extra_methods)s\
 
 %(examples)s\

pandas/core/dtypes/dtypes.py

@@ -39,7 +39,12 @@ class Registry(object):
     Registry for dtype inference
 
     The registry allows one to map a string repr of a extension
-    dtype to an extenstion dtype.
+    dtype to an extension dtype. The string alias can be used in several
+    places, including
+
+    * Series and Index constructors
+    * :meth:`pandas.array`
+    * :meth:`pandas.Series.astype`
 
     Multiple extension types can be registered.
     These are tried in order.
@@ -592,6 +597,7 @@ def __eq__(self, other):
                 str(self.tz) == str(other.tz))
 
 
+@register_extension_dtype
 class PeriodDtype(ExtensionDtype, PandasExtensionDtype):
     """
     A Period duck-typed class, suitable for holding a period with freq dtype.
@@ -854,4 +860,3 @@ def is_dtype(cls, dtype):
 _pandas_registry = Registry()
 
 _pandas_registry.register(DatetimeTZDtype)
-_pandas_registry.register(PeriodDtype)

pandas/tests/api/test_api.py

@@ -45,7 +45,13 @@ class TestPDApi(Base):
                'Period', 'PeriodIndex', 'RangeIndex', 'UInt64Index',
                'Series', 'SparseArray', 'SparseDataFrame', 'SparseDtype',
                'SparseSeries', 'Timedelta',
-               'TimedeltaIndex', 'Timestamp', 'Interval', 'IntervalIndex']
+               'TimedeltaIndex', 'Timestamp', 'Interval', 'IntervalIndex',
+               'IntervalArray',
+               'CategoricalDtype', 'PeriodDtype', 'IntervalDtype',
+               'DatetimeTZDtype',
+               'Int8Dtype', 'Int16Dtype', 'Int32Dtype', 'Int64Dtype',
+               'UInt8Dtype', 'UInt16Dtype', 'UInt32Dtype', 'UInt64Dtype',
+               ]
 
     # these are already deprecated; awaiting removal
     deprecated_classes = ['TimeGrouper']
@@ -57,7 +63,7 @@ class TestPDApi(Base):
     modules = ['np', 'datetime']
 
     # top-level functions
-    funcs = ['bdate_range', 'concat', 'crosstab', 'cut',
+    funcs = ['array', 'bdate_range', 'concat', 'crosstab', 'cut',
              'date_range', 'interval_range', 'eval',
              'factorize', 'get_dummies',
              'infer_freq', 'isna', 'isnull', 'lreshape',