array(data: 'Sequence[object] | AnyArrayLike', dtype: 'Dtype | None' = None, copy: 'bool' = True) -> 'ExtensionArray'

Notes

Omitting the dtype argument means pandas will attempt to infer the best array type from the values in the data. As new array types are added by pandas and 3rd party libraries, the "best" array type may change. We recommend specifying dtype to ensure that

1. the correct array type for the data is returned

2. the returned array type doesn't change as new extension types are added by pandas and third-party libraries

Additionally, if the underlying memory representation of the returned array matters, we recommend specifying the dtype as a concrete object rather than a string alias or allowing it to be inferred. For example, a future version of pandas or a 3rd-party library may include a dedicated ExtensionArray for string data. In this event, the following would no longer return a arrays.PandasArray backed by a NumPy array.

>>> pd.array(['a', 'b'], dtype=str)
<PandasArray>
['a', 'b']
Length: 2, dtype: str32

This would instead return the new ExtensionArray dedicated for string data. If you really need the new array to be backed by a NumPy array, specify that in the dtype.

>>> pd.array(['a', 'b'], dtype=np.dtype("<U1"))
<PandasArray>
['a', 'b']
Length: 2, dtype: str32

Finally, Pandas has arrays that mostly overlap with NumPy

• arrays.DatetimeArray

• arrays.TimedeltaArray

When data with a datetime64[ns] or timedelta64[ns] dtype is passed, pandas will always return a DatetimeArray or TimedeltaArray rather than a PandasArray . This is for symmetry with the case of timezone-aware data, which NumPy does not natively support.

>>> pd.array(['2015', '2016'], dtype='datetime64[ns]')
<DatetimeArray>
['2015-01-01 00:00:00', '2016-01-01 00:00:00']
Length: 2, dtype: datetime64[ns]

>>> pd.array(["1H", "2H"], dtype='timedelta64[ns]')
<TimedeltaArray>
['0 days 01:00:00', '0 days 02:00:00']
Length: 2, dtype: timedelta64[ns]

Parameters

data : Sequence of objects

The scalars inside :None:None:`data` should be instances of the scalar type for dtype . It's expected that :None:None:`data` represents a 1-dimensional array of data.

When :None:None:`data` is an Index or Series, the underlying array will be extracted from :None:None:`data`.

dtype : str, np.dtype, or ExtensionDtype, optional

The dtype to use for the array. This may be a NumPy dtype or an extension type registered with pandas using pandas.api.extensions.register_extension_dtype .

If not specified, there are two possibilities:

1. When :None:None:`data` is a Series , Index , or ExtensionArray , the dtype will be taken from the data.

2. Otherwise, pandas will attempt to infer the dtype from the data.

Note that when :None:None:`data` is a NumPy array, data.dtype is not used for inferring the array type. This is because NumPy cannot represent all the types of data that can be held in extension arrays.

Currently, pandas will infer an extension dtype for sequences of

============================== ======================================= Scalar Type Array Type ============================== ======================================= pandas.Interval pandas.arrays.IntervalArray pandas.Period pandas.arrays.PeriodArray datetime.datetime pandas.arrays.DatetimeArray datetime.timedelta pandas.arrays.TimedeltaArray int pandas.arrays.IntegerArray float pandas.arrays.FloatingArray str pandas.arrays.StringArray or pandas.arrays.ArrowStringArray bool pandas.arrays.BooleanArray ============================== =======================================

The ExtensionArray created when the scalar type is str is determined by pd.options.mode.string_storage if the dtype is not explicitly given.

For all other cases, NumPy's usual inference rules will be used.

versionchanged

Pandas infers nullable-integer dtype for integer data, string dtype for string data, and nullable-boolean dtype for boolean data.

versionchanged

Pandas now also infers nullable-floating dtype for float-like input data

copy : bool, default True

Whether to copy the data, even if not necessary. Depending on the type of :None:None:`data`, creating the new array may require copying data, even if copy=False .

Raises

ValueError

When :None:None:`data` is not 1-dimensional.

Returns

ExtensionArray

The newly created array.

Create an array.

See Also

Index

Construct a pandas Index.

Series

Construct a pandas Series.

Series.array

Extract the array stored within a Series.

arrays.PandasArray

ExtensionArray wrapping a NumPy array.

numpy.array

Construct a NumPy array.

Examples

If a dtype is not specified, pandas will infer the best dtype from the values. See the description of dtype for the types pandas infers for.

This example is valid syntax, but we were not able to check execution

>>> pd.array([1, 2])
<IntegerArray>
[1, 2]
Length: 2, dtype: Int64

This example is valid syntax, but we were not able to check execution

>>> pd.array([1, 2, np.nan])
<IntegerArray>
[1, 2, <NA>]
Length: 3, dtype: Int64

This example is valid syntax, but we were not able to check execution

>>> pd.array([1.1, 2.2])
<FloatingArray>
[1.1, 2.2]
Length: 2, dtype: Float64

This example is valid syntax, but we were not able to check execution

>>> pd.array(["a", None, "c"])
<StringArray>
['a', <NA>, 'c']
Length: 3, dtype: string

This example is valid syntax, but we were not able to check execution

>>> with pd.option_context("string_storage", "pyarrow"):
...     arr = pd.array(["a", None, "c"])
...

This example is valid syntax, but we were not able to check execution

>>> arr
<ArrowStringArray>
['a', <NA>, 'c']
Length: 3, dtype: string

This example is valid syntax, but we were not able to check execution

>>> pd.array([pd.Period('2000', freq="D"), pd.Period("2000", freq="D")])
<PeriodArray>
['2000-01-01', '2000-01-01']
Length: 2, dtype: period[D]

You can use the string alias for dtype

This example is valid syntax, but we were not able to check execution

>>> pd.array(['a', 'b', 'a'], dtype='category')
['a', 'b', 'a']
Categories (2, object): ['a', 'b']

Or specify the actual dtype

This example is valid syntax, but we were not able to check execution

>>> pd.array(['a', 'b', 'a'],
...          dtype=pd.CategoricalDtype(['a', 'b', 'c'], ordered=True))
['a', 'b', 'a']
Categories (3, object): ['a' < 'b' < 'c']

If pandas does not infer a dedicated extension type a arrays.PandasArray is returned.

This example is valid syntax, but we were not able to check execution

>>> pd.array([1 + 1j, 3 + 2j])
<PandasArray>
[(1+1j), (3+2j)]
Length: 2, dtype: complex128

As mentioned in the "Notes" section, new extension types may be added in the future (by pandas or 3rd party libraries), causing the return value to no longer be a arrays.PandasArray . Specify the dtype as a NumPy dtype if you need to ensure there's no future change in behavior.

This example is valid syntax, but we were not able to check execution

>>> pd.array([1, 2], dtype=np.dtype("int32"))
<PandasArray>
[1, 2]
Length: 2, dtype: int32

:None:None:`data` must be 1-dimensional. A ValueError is raised when the input has the wrong dimensionality.

This example is valid syntax, but we were not able to check execution

>>> pd.array(1)
Traceback (most recent call last):
  ...
ValueError: Cannot pass scalar '1' to 'pandas.array'.

See :

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /pandas/core/construction.py#76
type: <class 'function'>
Commit: