Skip to content

narwhals.dtypes

Array

List

Variable length list type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [["narwhal", "orca"], ["beluga", "vaquita"]]
>>> ser_pd = pd.Series(data, dtype=pd.ArrowDtype(pa.large_list(pa.large_string())))
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> nw.from_native(ser_pd, series_only=True).dtype
List(String)
>>> nw.from_native(ser_pl, series_only=True).dtype
List(String)
>>> nw.from_native(ser_pa, series_only=True).dtype
List(String)

Int64

64-bit signed integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> nw.from_native(ser_pd, series_only=True).dtype
Int64
>>> nw.from_native(ser_pl, series_only=True).dtype
Int64
>>> nw.from_native(ser_pa, series_only=True).dtype
Int64

Int32

32-bit signed integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> def func(ser):
...     ser_nw = nw.from_native(ser, series_only=True)
...     return ser_nw.cast(nw.Int32).dtype

>>> func(ser_pd)
Int32
>>> func(ser_pl)
Int32
>>> func(ser_pa)
Int32

Int16

16-bit signed integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

def func(ser): ... ser_nw = nw.from_native(ser, series_only=True) ... return ser_nw.cast(nw.Int16).dtype

func(ser_pd) Int16 func(ser_pl) Int16 func(ser_pa) Int16

Int8

8-bit signed integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> def func(ser):
...     ser_nw = nw.from_native(ser, series_only=True)
...     return ser_nw.cast(nw.Int8).dtype

>>> func(ser_pd)
Int8
>>> func(ser_pl)
Int8
>>> func(ser_pa)
Int8

UInt64

64-bit unsigned integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> def func(ser):
...     ser_nw = nw.from_native(ser, series_only=True)
...     return ser_nw.cast(nw.UInt64).dtype

>>> func(ser_pd)
UInt64
>>> func(ser_pl)
UInt64
>>> func(ser_pa)
UInt64

UInt32

32-bit unsigned integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> def func(ser):
...     ser_nw = nw.from_native(ser, series_only=True)
...     return ser_nw.cast(nw.UInt32).dtype

>>> func(ser_pd)
UInt32
>>> func(ser_pl)
UInt32
>>> func(ser_pa)
UInt32

UInt16

16-bit unsigned integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> def func(ser):
...     ser_nw = nw.from_native(ser, series_only=True)
...     return ser_nw.cast(nw.UInt16).dtype

>>> func(ser_pd)
UInt16
>>> func(ser_pl)
UInt16
>>> func(ser_pa)
UInt16

UInt8

8-bit unsigned integer type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [2, 1, 3, 7]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> def func(ser):
...     ser_nw = nw.from_native(ser, series_only=True)
...     return ser_nw.cast(nw.UInt8).dtype

>>> func(ser_pd)
UInt8
>>> func(ser_pl)
UInt8
>>> func(ser_pa)
UInt8

Field

Definition of a single field within a Struct DataType.

Parameters:

Name Type Description Default
name str

The name of the field within its parent Struct.

 required
dtype type[DType] | DType

The DataType of the field's values.

 required

Float64

64-bit floating point type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [0.001, 0.1, 0.01, 0.1]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> nw.from_native(ser_pd, series_only=True).dtype
Float64
>>> nw.from_native(ser_pl, series_only=True).dtype
Float64
>>> nw.from_native(ser_pa, series_only=True).dtype
Float64

Float32

32-bit floating point type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [0.001, 0.1, 0.01, 0.1]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> def func(ser):
...     ser_nw = nw.from_native(ser, series_only=True)
...     return ser_nw.cast(nw.Float32).dtype

>>> func(ser_pd)
Float32
>>> func(ser_pl)
Float32
>>> func(ser_pa)
Float32

Boolean

Boolean type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [True, False, False, True]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> nw.from_native(ser_pd, series_only=True).dtype
Boolean
>>> nw.from_native(ser_pl, series_only=True).dtype
Boolean
>>> nw.from_native(ser_pa, series_only=True).dtype
Boolean

Categorical

A categorical encoding of a set of strings.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = ["beluga", "narwhal", "orca", "vaquita"]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> nw.from_native(ser_pd, series_only=True).cast(nw.Categorical).dtype
Categorical
>>> nw.from_native(ser_pl, series_only=True).cast(nw.Categorical).dtype
Categorical
>>> nw.from_native(ser_pa, series_only=True).cast(nw.Categorical).dtype
Categorical

Enum

String

UTF-8 encoded string type.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = ["beluga", "narwhal", "orca", "vaquita"]
>>> ser_pd = pd.Series(data)
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> nw.from_native(ser_pd, series_only=True).dtype
String
>>> nw.from_native(ser_pl, series_only=True).dtype
String
>>> nw.from_native(ser_pa, series_only=True).dtype
String

Struct

Struct composite type.

Parameters:

Name Type Description Default
fields Sequence[Field] | Mapping[str, DType | type[DType]]

The fields that make up the struct. Can be either a sequence of Field objects or a mapping of column names to data types.

 required

Examples:

>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [{"a": 1, "b": ["narwhal", "beluga"]}, {"a": 2, "b": ["orca"]}]
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([data])

>>> nw.from_native(ser_pl, series_only=True).dtype
Struct({'a': Int64, 'b': List(String)})
>>> nw.from_native(ser_pa, series_only=True).dtype
Struct({'a': Int64, 'b': List(String)})

to_schema()

Return Struct dtype as a schema dict.

Returns:

Type Description
OrderedDict[str, DType | type[DType]]

Mapping from column name to dtype.

Date

Datetime

Data type representing a calendar date and time of day.

Parameters:

Name Type Description Default
time_unit Literal['us', 'ns', 'ms', 's']

Unit of time. Defaults to 'us' (microseconds).

 'us'
time_zone str | timezone | None

Time zone string, as defined in zoneinfo (to see valid strings run import zoneinfo; zoneinfo.available_timezones() for a full list).

 None
Notes

Adapted from Polars implementation at: https://github.com/pola-rs/polars/blob/py-1.7.1/py-polars/polars/datatypes/classes.py#L398-L457

Duration

Data type representing a time duration.

Parameters:

Name Type Description Default
time_unit Literal['us', 'ns', 'ms', 's']

Unit of time. Defaults to 'us' (microseconds).

 'us'
Notes

Adapted from Polars implementation at: https://github.com/pola-rs/polars/blob/py-1.7.1/py-polars/polars/datatypes/classes.py#L460-L502

Object

Unknown