Levels

Narwhals comes with two levels of support: "full" and "interchange".

Libraries for which we have full support can benefit from the whole Narwhals API.

For example:

import narwhals as nw
from narwhals.typing import FrameT


@nw.narwhalify
def func(df: FrameT) -> FrameT:
    return df.group_by("a").agg(
        b_mean=nw.col("b").mean(),
        b_std=nw.col("b").std(),
    )

will work for any of pandas, Polars, cuDF, Modin, and PyArrow.

However, sometimes you don't need to do complex operations on dataframes - all you need is to inspect the schema a bit before making other decisions, such as which columns to select or whether to convert to another library. For that purpose, we also provide "interchange" level of support. If a library implements the Dataframe Interchange Protocol, then a call such as

from typing import Any

import narwhals as nw
from narwhals.schema import Schema


def func(df: Any) -> Schema:
    df = nw.from_native(df, eager_or_interchange_only=True)
    return df.schema

is also supported, meaning that, in addition to the libraries mentioned above, you can also pass Ibis, Vaex, PyArrow, and any other library which implements the protocol.