metaxy: Skill for Claude Code

Narwhals - DataFrame Agnostic API

Narwhals is a lightweight, zero-dependency compatibility layer for dataframe libraries in Python that provides a unified interface across different backends.

Docs: https://narwhals-dev.github.io/narwhals/

What is Narwhals?

Narwhals enables writing dataframe-agnostic code that works seamlessly across multiple Python dataframe libraries:

Full API Support:

• cuDF
• Modin
• pandas
• Polars
• PyArrow

Lazy-Only Support:

• Dask
• DuckDB
• Ibis
• PySpark
• SQLFrame

Core Philosophy

Why Narwhals?

• Resolves subtle differences between libraries (e.g., pandas checking index vs Polars checking values)
• Provides unified, simple, and predictable API
• Handles backwards compatibility internally
• Tests against nightly builds of supported libraries
• Maintains negligible performance overhead
• Full static typing support
• Zero dependencies

Target Use Case: Anyone building libraries, applications, or services that consume dataframes and need complete backend independence.

Key Features

1. Backend Agnostic: Write once, run on any supported dataframe library
2. Polars-Like API: Uses a subset of the Polars API for consistency
3. Lazy & Eager Execution: Separate APIs for both execution modes
4. Expression Support: Full expression API for complex operations
5. Type Safety: Perfect static typing support
6. 100% Branch Coverage: Thoroughly tested

Basic Usage Pattern

Three-Step Workflow

import narwhals as nw

# 1. Convert to Narwhals
df_nw = nw.from_native(df)  # Works with pandas, Polars, PyArrow, etc.

# 2. Perform operations using Polars-like API
result = df_nw.select(a_sum=nw.col("a").sum(), a_mean=nw.col("a").mean(), b_std=nw.col("b").std())

# 3. Convert back to original library
result_native = result.to_native()

Using the @narwhalify Decorator

Simplifies function definitions for automatic conversion:

@nw.narwhalify
def my_func(df: IntoDataFrameT):
    return df.select(nw.col("a").sum(), nw.col("b").mean()).filter(nw.col("a") > 0)


# Automatically handles conversion to/from Narwhals
result = my_func(pandas_df)  # Works!
result = my_func(polars_df)  # Also works!