`narwhals.dtypes`

`Array`

Fixed length list type.

Parameters:

Name	Type	Description	Default
`inner`	`DType \| type[DType]`	The datatype of the values within each array.	required
`shape`	`int \| tuple[int, ...]`	The shape of the arrays.	required

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([[1, 2], [3, 4], [5, 6]], dtype=pl.Array(pl.Int32, 2))
>>> nw.from_native(s_native, series_only=True).dtype
Array(Int32, shape=(2,))

`Decimal`

Decimal type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s = pl.Series(["1.5"], dtype=pl.Decimal)
>>> nw.from_native(s, series_only=True).dtype
Decimal

`List`

Variable length list type.

Examples:

>>> import pandas as pd
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pd.Series(
...     [["narwhal", "orca"], ["beluga", "vaquita"]],
...     dtype=pd.ArrowDtype(pa.large_list(pa.large_string())),
... )
>>> nw.from_native(s_native, series_only=True).dtype
List(String)

`Int128`

128-bit signed integer type.

`Int64`

64-bit signed integer type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.Int64).dtype
Int64

`Int32`

32-bit signed integer type.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array([[2, 1, 3, 7]])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.Int32).dtype
Int32

`Int16`

16-bit signed integer type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.Int16).dtype
Int16

`Int8`

8-bit signed integer type.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.Int8).dtype
Int8

`IntegerType`

Base class for integer data types.

`UInt128`

128-bit unsigned integer type.

`UInt64`

64-bit unsigned integer type.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.UInt64).dtype
UInt64

`UInt32`

32-bit unsigned integer type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.UInt32).dtype
UInt32

`UInt16`

16-bit unsigned integer type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.UInt16).dtype
UInt16

`UInt8`

8-bit unsigned integer type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.UInt8).dtype
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

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>> data = [{"a": 1, "b": ["narwhal", "beluga"]}, {"a": 2, "b": ["orca"]}]
>>> ser_pa = pa.chunked_array([data])
>>> nw.from_native(ser_pa, series_only=True).dtype.fields
[Field('a', Int64), Field('b', List(String))]

`Float64`

64-bit floating point type.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array([[0.001, 0.1, 0.01, 0.1]])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.Float64).dtype
Float64

`Float32`

32-bit floating point type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([0.001, 0.1, 0.01, 0.1])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.cast(nw.Float32).dtype
Float32

`FloatType`

Base class for float data types.

`Boolean`

Boolean type.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array([[True, False, False, True]])
>>> nw.from_native(s_native, series_only=True).dtype
Boolean

`Categorical`

A categorical encoding of a set of strings.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series(["beluga", "narwhal", "orca"])
>>> nw.from_native(s_native, series_only=True).cast(nw.Categorical).dtype
Categorical

`Enum`

A fixed categorical encoding of a unique set of strings.

Polars has an Enum data type, while pandas and PyArrow do not.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> data = ["beluga", "narwhal", "orca"]
>>> s_native = pl.Series(data, dtype=pl.Enum(data))
>>> nw.from_native(s_native, series_only=True).dtype
Enum

`NestedType`

Base class for nested data types.

`SignedIntegerType`

Base class for signed integer data types.

`String`

UTF-8 encoded string type.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(["beluga", "narwhal", "orca", "vaquita"])
>>> nw.from_native(s_native, 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 pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[{"a": 1, "b": ["narwhal", "beluga"]}, {"a": 2, "b": ["orca"]}]]
... )
>>> nw.from_native(s_native, series_only=True).dtype
Struct({'a': Int64, 'b': List(String)})

`to_schema() -> OrderedDict[str, DType | type[DType]]`

Return Struct dtype as a schema dict.

Returns:

Type	Description
`OrderedDict[str, DType \| type[DType]]`	Mapping from column name to dtype.

`Date`

Data type representing a calendar date.

Examples:

>>> from datetime import date, timedelta
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[date(2024, 12, 1) + timedelta(days=d) for d in range(4)]]
... )
>>> nw.from_native(s_native, series_only=True).dtype
Date

`Datetime`

Data type representing a calendar date and time of day.

Parameters:

Name	Type	Description	Default
`time_unit`	`TimeUnit`	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

Examples:

>>> from datetime import datetime, timedelta
>>> import polars as pl
>>> import narwhals as nw
>>> s_native = (
...     pl.Series([datetime(2024, 12, 9) + timedelta(days=n) for n in range(5)])
...     .cast(pl.Datetime("ms"))
...     .dt.replace_time_zone("Africa/Accra")
... )
>>> nw.from_native(s_native, series_only=True).dtype
Datetime(time_unit='ms', time_zone='Africa/Accra')

`Duration`

Data type representing a time duration.

Parameters:

Name	Type	Description	Default
`time_unit`	`TimeUnit`	Unit of time. Defaults to `'us'` (microseconds).	`'us'`

Notes

Adapted from Polars implementation

Examples:

>>> from datetime import timedelta
>>> import pyarrow as pa
>>> import narwhals as nw
>>> s_native = pa.chunked_array(
...     [[timedelta(seconds=d) for d in range(1, 4)]], type=pa.duration("ms")
... )
>>> nw.from_native(s_native, series_only=True).dtype
Duration(time_unit='ms')

`Object`

Data type for wrapping arbitrary Python objects.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> class Foo: ...
>>> s_native = pd.Series([Foo(), Foo()])
>>> nw.from_native(s_native, series_only=True).dtype
Object

`Unknown`

Type representing DataType values that could not be determined statically.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series(pd.period_range("2000-01", periods=4, freq="M"))
>>> nw.from_native(s_native, series_only=True).dtype
Unknown

`UnsignedIntegerType`

Base class for unsigned integer data types.

`Time`

Data type representing the time of day.

Examples:

>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> import duckdb
>>> from datetime import time
>>> data = [time(9, 0), time(9, 1, 10), time(9, 2)]
>>> ser_pl = pl.Series(data)
>>> ser_pa = pa.chunked_array([pa.array(data, type=pa.time64("ns"))])
>>> rel = duckdb.sql(
...     " SELECT * FROM (VALUES (TIME '12:00:00'), (TIME '14:30:15')) df(t)"
... )

>>> nw.from_native(ser_pl, series_only=True).dtype
Time
>>> nw.from_native(ser_pa, series_only=True).dtype
Time
>>> nw.from_native(rel).schema["t"]
Time

`Binary`

Binary type.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> import pyarrow as pa
>>> import duckdb
>>> data = [b"test1", b"test2"]
>>> ser_pl = pl.Series(data, dtype=pl.Binary)
>>> ser_pa = pa.chunked_array([pa.array(data, type=pa.binary())])
>>> rel = duckdb.sql(
...     "SELECT * FROM (VALUES (BLOB 'test1'), (BLOB 'test2')) AS df(t)"
... )

>>> nw.from_native(ser_pl, series_only=True).dtype
Binary
>>> nw.from_native(ser_pa, series_only=True).dtype
Binary
>>> nw.from_native(rel).schema["t"]
Binary