narwhals.dtypes
DType
Base class for all Narwhals data types.
__eq__
__eq__(other: DType | type[DType]) -> bool
Check if this DType is equivalent to another DType.
Examples:
>>> import narwhals as nw
>>> nw.String() == nw.String()
True
>>> nw.String() == nw.String
True
>>> nw.Int16() == nw.Int32
False
>>> nw.Boolean() == nw.Int8
False
>>> nw.Date() == nw.Datetime
False
base_type
classmethod
base_type() -> type[Self]
Return this DType's fundamental/root type class.
Examples:
>>> import narwhals as nw
>>> nw.Datetime("us").base_type()
Datetime
>>> nw.String.base_type()
String
>>> nw.List(nw.Int64).base_type()
List
is_boolean
classmethod
is_boolean() -> bool
Check whether the data type is a boolean type.
is_decimal
classmethod
is_decimal() -> bool
Check whether the data type is a decimal type.
is_float
classmethod
is_float() -> bool
Check whether the data type is a floating point type.
is_integer
classmethod
is_integer() -> bool
Check whether the data type is an integer type.
is_nested
classmethod
is_nested() -> bool
Check whether the data type is a nested type.
is_numeric
classmethod
is_numeric() -> bool
Check whether the data type is a numeric type.
is_signed_integer
classmethod
is_signed_integer() -> bool
Check whether the data type is a signed integer type.
is_temporal
classmethod
is_temporal() -> bool
Check whether the data type is a temporal type.
is_unsigned_integer
classmethod
is_unsigned_integer() -> bool
Check whether the data type is an unsigned integer type.
NumericType
Decimal
Bases: NumericType
Decimal 128-bit type with an optional precision and non-negative scale.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
precision
|
int | None
|
Maximum number of digits in each number. If set to |
None
|
scale
|
int
|
Number of digits to the right of the decimal point in each number. |
0
|
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(precision=2, scale=1)
FloatType
Float32
Bases: FloatType
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
Float64
Bases: FloatType
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
IntegerType
SignedIntegerType
Int8
Bases: SignedIntegerType
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
Int16
Bases: SignedIntegerType
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
Int32
Bases: SignedIntegerType
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
Int64
Bases: SignedIntegerType
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
Int128
Bases: SignedIntegerType
128-bit signed integer type.
Examples:
>>> import polars as pl
>>> import pyarrow as pa
>>> import narwhals as nw
>>> import duckdb
>>> s_native = pl.Series([2, 1, 3, 7])
>>> s = nw.from_native(s_native, series_only=True)
>>> df_native = pa.table({"a": [2, 1, 3, 7]})
>>> rel = duckdb.sql(" SELECT CAST (a AS INT128) AS a FROM df_native ")
>>> s.cast(nw.Int128).dtype
Int128
>>> nw.from_native(rel).collect_schema()["a"]
Int128
UnsignedIntegerType
UInt8
Bases: UnsignedIntegerType
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
UInt16
Bases: UnsignedIntegerType
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
UInt32
Bases: UnsignedIntegerType
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
UInt64
Bases: UnsignedIntegerType
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
UInt128
Bases: UnsignedIntegerType
128-bit unsigned integer type.
Examples:
>>> import pandas as pd
>>> import narwhals as nw
>>> import duckdb
>>> df_native = pd.DataFrame({"a": [2, 1, 3, 7]})
>>> rel = duckdb.sql(" SELECT CAST (a AS UINT128) AS a FROM df_native ")
>>> nw.from_native(rel).collect_schema()["a"]
UInt128
TemporalType
Date
Bases: TemporalType
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
Bases: TemporalType
Data type representing a calendar date and time of day.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time_unit
|
TimeUnit
|
Unit of time. Defaults to |
'us'
|
time_zone
|
str | timezone | None
|
Time zone string, as defined in zoneinfo (to see valid strings run
|
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')
time_unit
instance-attribute
time_unit: TimeUnit = time_unit
Unit of time.
time_zone
instance-attribute
time_zone: str | None = time_zone
Time zone string, as defined in zoneinfo.
Notes
To see valid strings run import zoneinfo; zoneinfo.available_timezones() for a full list.
__eq__
__eq__(other: DType | type[DType]) -> bool
Check if this Datetime is equivalent to another DType.
Examples:
>>> import narwhals as nw
>>> nw.Datetime("s") == nw.Datetime("s")
True
>>> nw.Datetime() == nw.Datetime("us")
True
>>> nw.Datetime("us") == nw.Datetime("ns")
False
>>> nw.Datetime("us", "UTC") == nw.Datetime(time_unit="us", time_zone="UTC")
True
>>> nw.Datetime(time_zone="UTC") == nw.Datetime(time_zone="EST")
False
>>> nw.Datetime() == nw.Duration()
False
>>> nw.Datetime("ms") == nw.Datetime
True
Duration
Bases: TemporalType
Data type representing a time duration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time_unit
|
TimeUnit
|
Unit of time. Defaults to |
'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')
time_unit
instance-attribute
time_unit: TimeUnit = time_unit
Unit of time.
__eq__
__eq__(other: DType | type[DType]) -> bool
Check if this Duration is equivalent to another DType.
Examples:
>>> import narwhals as nw
>>> nw.Duration("us") == nw.Duration("us")
True
>>> nw.Duration() == nw.Duration("us")
True
>>> nw.Duration("us") == nw.Duration("ns")
False
>>> nw.Duration() == nw.Datetime()
False
>>> nw.Duration("ms") == nw.Duration
True
Time
Bases: TemporalType
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).collect_schema()["t"]
Time
NestedType
Array
Bases: NestedType
Fixed length list type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inner
|
IntoDType
|
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,))
inner
instance-attribute
inner: IntoDType
The DType of the values within each array.
shape
instance-attribute
shape: tuple[int, ...]
The shape of the arrays.
size
instance-attribute
size: int
The size of the Array.
__eq__
__eq__(other: DType | type[DType]) -> bool
Check if this Array is equivalent to another DType.
Examples:
>>> import narwhals as nw
>>> nw.Array(nw.Int64, 2) == nw.Array(nw.Int64, 2)
True
>>> nw.Array(nw.Int64, 2) == nw.Array(nw.String, 2)
False
>>> nw.Array(nw.Int64, 2) == nw.Array(nw.Int64, 4)
False
If a parent type is not specific about its inner type, we infer it as equal
>>> nw.Array(nw.Int64, 2) == nw.Array
True
List
Bases: NestedType
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)
inner
instance-attribute
inner: IntoDType = inner
The DType of the values within each list.
__eq__
__eq__(other: DType | type[DType]) -> bool
Check if this List is equivalent to another DType.
Examples:
>>> import narwhals as nw
>>> nw.List(nw.Int64) == nw.List(nw.Int64)
True
>>> nw.List(nw.Int64) == nw.List(nw.Float32)
False
If a parent type is not specific about its inner type, we infer it as equal
>>> nw.List(nw.Int64) == nw.List
True
Field
Definition of a single field within a Struct DType.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The name of the field within its parent |
required |
dtype
|
IntoDType
|
The |
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))]
dtype
instance-attribute
dtype: IntoDType = dtype
The DType of the field's values.
name
instance-attribute
name: str = name
The name of the field within its parent Struct.
__eq__
__eq__(other: Field) -> bool
Check if this Field is equivalent to another Field.
Two fields are equivalent if they have the same name and the same dtype.
Examples:
>>> import narwhals as nw
>>> nw.Field("a", nw.String) == nw.Field("a", nw.String())
True
>>> nw.Field("a", nw.String) == nw.Field("a", nw.String)
True
>>> nw.Field("a", nw.String) == nw.Field("a", nw.Datetime)
False
>>> nw.Field("a", nw.String) == nw.Field("b", nw.String)
False
>>> nw.Field("a", nw.String) == nw.String
False
Struct
Bases: NestedType
Struct composite type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fields
|
Sequence[Field] | Mapping[str, IntoDType]
|
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)})
fields
instance-attribute
fields: list[Field]
The fields that make up the struct.
__eq__
__eq__(other: DType | type[DType]) -> bool
Check if this Struct is equivalent to another DType.
Examples:
>>> import narwhals as nw
>>> nw.Struct({"a": nw.Int64}) == nw.Struct({"a": nw.Int64})
True
>>> nw.Struct({"a": nw.Int64}) == nw.Struct({"a": nw.Boolean})
False
>>> nw.Struct({"a": nw.Int64}) == nw.Struct({"b": nw.Int64})
False
>>> nw.Struct({"a": nw.Int64}) == nw.Struct([nw.Field("a", nw.Int64)])
True
If a parent type is not specific about its inner type, we infer it as equal
>>> nw.Struct({"a": nw.Int64}) == nw.Struct
True
to_schema
to_schema() -> OrderedDict[str, IntoDType]
Return Struct dtype as a schema dict.
String
Bases: DType
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
Categorical
Bases: DType
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
Bases: DType
A fixed categorical encoding of a unique set of strings.
Polars has an Enum data type. In pandas, ordered categories get mapped to Enum. PyArrow has no Enum equivalent.
Examples:
>>> import narwhals as nw
>>> nw.Enum(["beluga", "narwhal", "orca"])
Enum(categories=['beluga', 'narwhal', 'orca'])
categories
property
categories: tuple[str, ...]
The categories in the dataset.
__eq__
__eq__(other: DType | type[DType]) -> bool
Check if this Enum is equivalent to another DType.
Examples:
>>> import narwhals as nw
>>> nw.Enum(["a", "b", "c"]) == nw.Enum(["a", "b", "c"])
True
>>> import polars as pl
>>> categories = pl.Series(["a", "b", "c"])
>>> nw.Enum(["a", "b", "c"]) == nw.Enum(categories)
True
>>> nw.Enum(["a", "b", "c"]) == nw.Enum(["b", "a", "c"])
False
>>> nw.Enum(["a", "b", "c"]) == nw.Enum(["a"])
False
>>> nw.Enum(["a", "b", "c"]) == nw.Categorical
False
>>> nw.Enum(["a", "b", "c"]) == nw.Enum
True
Binary
Bases: DType
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).collect_schema()["t"]
Binary
Boolean
Bases: DType
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
Object
Bases: DType
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
Bases: DType
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