Skip to content

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 module-attribute 

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

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 module-attribute 

Frame: TypeAlias = Union["DataFrame[Any]", "LazyFrame[Any]"]

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 module-attribute 

FrameT = TypeVar('FrameT', bound='Frame')

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 module-attribute 

IntoDataFrame: TypeAlias = Union[
    "NativeFrame", "DataFrameLike"
]

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 module-attribute 

IntoDataFrameT = TypeVar(
    "IntoDataFrameT", bound="IntoDataFrame"
)

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 module-attribute 

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

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 module-attribute 

IntoFrame: TypeAlias = Union[
    "IntoDataFrame", "IntoLazyFrame"
]

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 module-attribute 

IntoFrameT = TypeVar('IntoFrameT', bound='IntoFrame')

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 module-attribute 

IntoSeries: TypeAlias = 'NativeSeries'

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 module-attribute 

IntoSeriesT = TypeVar('IntoSeriesT', bound='IntoSeries')

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()

SizeUnit module-attribute 

SizeUnit: TypeAlias = Literal[
    "b",
    "kb",
    "mb",
    "gb",
    "tb",
    "bytes",
    "kilobytes",
    "megabytes",
    "gigabytes",
    "terabytes",
]

TimeUnit module-attribute 

TimeUnit: TypeAlias = Literal['ns', 'us', 'ms', 's']

AsofJoinStrategy module-attribute 

AsofJoinStrategy: TypeAlias = Literal[
    "backward", "forward", "nearest"
]

Join strategy.

  • "backward": Selects the last row in the right DataFrame whose on key is less than or equal to the left's key.
  • "forward": Selects the first row in the right DataFrame whose on key is greater than or equal to the left's key.
  • "nearest": Search selects the last row in the right DataFrame whose value is nearest to the left's key.

ClosedInterval module-attribute 

ClosedInterval: TypeAlias = Literal[
    "left", "right", "none", "both"
]

Define which sides of the interval are closed (inclusive).

ConcatMethod module-attribute 

ConcatMethod: TypeAlias = Literal[
    "horizontal", "vertical", "diagonal"
]

Concatenating strategy.

  • "vertical": Concatenate vertically. Column names must match.
  • "horizontal": Concatenate horizontally. If lengths don't match, then missing rows are filled with null values.
  • "diagonal": Finds a union between the column schemas and fills missing column values with null.

FillNullStrategy module-attribute 

FillNullStrategy: TypeAlias = Literal["forward", "backward"]

Strategy used to fill null values.

JoinStrategy module-attribute 

JoinStrategy: TypeAlias = Literal[
    "inner", "left", "full", "cross", "semi", "anti"
]

Join strategy.

  • "inner": Returns rows that have matching values in both tables.
  • "left": Returns all rows from the left table, and the matched rows from the right table.
  • "full": Returns all rows in both dataframes, with the suffix appended to the right join keys.
  • "cross": Returns the Cartesian product of rows from both tables.
  • "semi": Filter rows that have a match in the right table.
  • "anti": Filter rows that do not have a match in the right table.

PivotAgg module-attribute 

PivotAgg: TypeAlias = Literal[
    "min",
    "max",
    "first",
    "last",
    "sum",
    "mean",
    "median",
    "len",
]

A predefined aggregate function string.

RankMethod module-attribute 

RankMethod: TypeAlias = Literal[
    "average", "min", "max", "dense", "ordinal"
]

The method used to assign ranks to tied elements.

  • "average": The average of the ranks that would have been assigned to all the tied values is assigned to each value.
  • "min": The minimum of the ranks that would have been assigned to all the tied values is assigned to each value. (This is also referred to as "competition" ranking.)
  • "max": The maximum of the ranks that would have been assigned to all the tied values is assigned to each value.
  • "dense": Like "min", but the rank of the next highest element is assigned the rank immediately after those assigned to the tied elements.
  • "ordinal": All values are given a distinct rank, corresponding to the order that the values occur in the Series.

RollingInterpolationMethod module-attribute 

RollingInterpolationMethod: TypeAlias = Literal[
    "nearest", "higher", "lower", "midpoint", "linear"
]

Interpolation method.

UniqueKeepStrategy module-attribute 

UniqueKeepStrategy: TypeAlias = Literal[
    "any", "first", "last", "none"
]

Which of the duplicate rows to keep.

  • "any": Does not give any guarantee of which row is kept. This allows more optimizations.
  • "none": Don't keep duplicate rows.
  • "first": Keep first unique row.
  • "last": Keep last unique row.

LazyUniqueKeepStrategy module-attribute 

LazyUniqueKeepStrategy: TypeAlias = Literal['any', 'none']

Which of the duplicate rows to keep.

  • "any": Does not give any guarantee of which row is kept.
  • "none": Don't keep duplicate rows.

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.