narwhals.typing

Narwhals comes fully statically typed. In addition to nw.DataFrame, nw.Expr, nw.Series, nw.LazyFrame, we also provide the following type hints:

DataFrameT = TypeVar('DataFrameT', bound='DataFrame[Any]') module-attribute

TypeVar bound to Narwhals DataFrame.

Use this if your function can accept a Narwhals DataFrame and returns a Narwhals DataFrame backed by the same backend.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import DataFrameT
>>> @nw.narwhalify
>>> def func(df: DataFrameT) -> DataFrameT:
...     return df.with_columns(c=df["a"] + 1)

Frame: TypeAlias = Union['DataFrame[Any]', 'LazyFrame[Any]'] module-attribute

Narwhals DataFrame or Narwhals LazyFrame.

Use this if your function can work with either and your function doesn't care about its backend.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import Frame
>>> @nw.narwhalify
... def agnostic_columns(df: Frame) -> list[str]:
...     return df.columns

FrameT = TypeVar('FrameT', bound='Frame') module-attribute

TypeVar bound to Narwhals DataFrame or Narwhals LazyFrame.

Use this if your function accepts either nw.DataFrame or nw.LazyFrame and returns an object of the same kind.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import FrameT
>>> @nw.narwhalify
... def agnostic_func(df: FrameT) -> FrameT:
...     return df.with_columns(c=nw.col("a") + 1)

IntoDataFrame: TypeAlias = Union['NativeFrame', 'DataFrame[Any]', 'DataFrameLike'] module-attribute

Anything which can be converted to a Narwhals DataFrame.

Use this if your function accepts a narwhalifiable object but doesn't care about its backend.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import IntoDataFrame
>>> def agnostic_shape(df_native: IntoDataFrame) -> tuple[int, int]:
...     df = nw.from_native(df_native, eager_only=True)
...     return df.shape

IntoDataFrameT = TypeVar('IntoDataFrameT', bound='IntoDataFrame') module-attribute

TypeVar bound to object convertible to Narwhals DataFrame.

Use this if your function accepts an object which can be converted to nw.DataFrame and returns an object of the same class.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import IntoDataFrameT
>>> def agnostic_func(df_native: IntoDataFrameT) -> IntoDataFrameT:
...     df = nw.from_native(df_native, eager_only=True)
...     return df.with_columns(c=df["a"] + 1).to_native()

IntoExpr: TypeAlias = Union['Expr', str, 'Series[Any]'] module-attribute

Anything which can be converted to an expression.

Use this to mean "either a Narwhals expression, or something which can be converted into one". For example, exprs in DataFrame.select is typed to accept IntoExpr, as it can either accept a nw.Expr (e.g. df.select(nw.col('a'))) or a string which will be interpreted as a nw.Expr, e.g. df.select('a').

IntoFrame: TypeAlias = Union['NativeFrame', 'DataFrame[Any]', 'LazyFrame[Any]', 'DataFrameLike'] module-attribute

Anything which can be converted to a Narwhals DataFrame or LazyFrame.

Use this if your function can accept an object which can be converted to either nw.DataFrame or nw.LazyFrame and it doesn't care about its backend.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import IntoFrame
>>> def agnostic_columns(df_native: IntoFrame) -> list[str]:
...     df = nw.from_native(df_native)
...     return df.collect_schema().names()

IntoFrameT = TypeVar('IntoFrameT', bound='IntoFrame') module-attribute

TypeVar bound to object convertible to Narwhals DataFrame or Narwhals LazyFrame.

Use this if your function accepts an object which is convertible to nw.DataFrame or nw.LazyFrame and returns an object of the same type.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import IntoFrameT
>>> def agnostic_func(df_native: IntoFrameT) -> IntoFrameT:
...     df = nw.from_native(df_native)
...     return df.with_columns(c=nw.col("a") + 1).to_native()

IntoSeries: TypeAlias = Union['Series[Any]', 'NativeSeries'] module-attribute

Anything which can be converted to a Narwhals Series.

Use this if your function can accept an object which can be converted to nw.Series and it doesn't care about its backend.

Examples:

>>> from typing import Any
>>> import narwhals as nw
>>> from narwhals.typing import IntoSeries
>>> def agnostic_to_list(s_native: IntoSeries) -> list[Any]:
...     s = nw.from_native(s_native)
...     return s.to_list()

IntoSeriesT = TypeVar('IntoSeriesT', bound='IntoSeries') module-attribute

TypeVar bound to object convertible to Narwhals Series.

Use this if your function accepts an object which can be converted to nw.Series and returns an object of the same class.

Examples:

>>> import narwhals as nw
>>> from narwhals.typing import IntoSeriesT
>>> def agnostic_abs(s_native: IntoSeriesT) -> IntoSeriesT:
...     s = nw.from_native(s_native, series_only=True)
...     return s.abs().to_native()

nw.narwhalify, or nw.from_native?

Although some people find the former more readable, the latter is better at preserving type hints.

Here's an example:

import polars as pl
import narwhals as nw
from narwhals.typing import IntoDataFrameT, DataFrameT

df = pl.DataFrame({"a": [1, 2, 3]})


def func(df_native: IntoDataFrameT) -> IntoDataFrameT:
    df = nw.from_native(df_native, eager_only=True)
    return df.select(b=nw.col("a")).to_native()


reveal_type(func(df))


@nw.narwhalify(strict=True)
def func_2(df: DataFrameT) -> DataFrameT:
    return df.select(b=nw.col("a"))


reveal_type(func_2(df))

Running mypy on it gives:

$ mypy t.py 
t.py:13: note: Revealed type is "polars.dataframe.frame.DataFrame"
t.py:21: note: Revealed type is "Any"
Success: no issues found in 1 source file

In the first case, mypy can infer that df is a polars.DataFrame. In the second case, it can't.

If you want to make the most out of type hints and preserve them as much as possible, we recommend nw.from_native and nw.to_native. Type hints will still be respected inside the function body if you type the arguments.