docs on raising

Author: TomAugspurger

doc/source/whatsnew/v0.24.0.rst

@@ -160,7 +160,7 @@ Reduction and groupby operations such as 'sum' work.
 
 .. _whatsnew_0240.enhancements.array:
 
-A new top-level method :func:`array` has been added for creating arrays (:issue:`22860`).
+A new top-level method :func:`array` has been added for creating 1-dimensional arrays (:issue:`22860`).
 This can be used to create any :ref:`extension array <extending.extension-types>`, including
 extension arrays registered by :ref:`3rd party libraries <ecosystem.extensions>`, or to
 create NumPy arrays.

pandas/core/arrays/array_.py

@@ -23,7 +23,8 @@ def array(data,         # type: Sequence[object]
     ----------
     data : Sequence of objects
         The scalars inside `data` should be instances of the
-        scalar type for `dtype`.
+        scalar type for `dtype`. It's expected that `data`
+        represents a 1-dimensional array of data.
 
         When `data` is an Index or Series, the underlying array
         will be extracted from `data`.
@@ -81,6 +82,11 @@ def array(data,         # type: Sequence[object]
     -------
     array : Union[numpy.ndarray, ExtensionArray]
 
+    Raises
+    ------
+    ValueError
+        When `data` is not 1-dimensional.
+
     See Also
     --------
     numpy.array : Construct a NumPy array.
@@ -134,14 +140,23 @@ def array(data,         # type: Sequence[object]
     the dtype:
 
     >>> pd.array([1, 2, np.nan], dtype='Int64')
-    IntegerArray([1, 2, nan], dtype='Int64')
+    <IntegerArray>
+    [1, 2, NaN]
+    Length: 3, dtype: Int64
 
     Pandas will infer an ExtensionArray for some types of data:
 
     >>> pd.array([pd.Period('2000', freq="D"), pd.Period("2000", freq="D")])
     <PeriodArray>
     ['2000-01-01', '2000-01-01']
     Length: 2, dtype: period[D]
+
+    A ValueError is raised when the input has the wrong dimensionality.
+
+    >>> pd.array(1)
+    Traceback (most recent call last):
+      ...
+    ValueError: Cannot pass scalar '1' to 'pandas.array'.
     """
     from pandas.core.arrays import (
         period_array, ExtensionArray, IntervalArray