polars-list-math 0.1.1

List-oriented math and expression helpers for Polars.

polars-list-math

polars-list-math is a Python/Rust package with list-oriented expression helpers for Polars.

Import the package once to register extra methods on Expr.list:

import polars as pl
import polars_list_math  # noqa: F401

Install

pip install polars-list-math
# or
uv add polars-list-math

Requires Python 3.12+ and polars>=1.39.3.

Methods

Method	Result	Docs
Expr.list.zip(...)	Zip lists into list[struct]	Polars proposal
Expr.list.combinations(...)	Pair each item with itself and later items in the same list	Combinations
Expr.list.combinations_to(...)	Pair each item with each item from another list	Combinations
Expr.list.similarity(...)	Weighted similarity between two lists	Similarity
Expr.list.mean_similarity(...)	Mean similarity inside a nested-list row	Similarity
Expr.list.mean_similarity_to(...)	Mean similarity to reference nested lists	Similarity

The Python helper py_list_similarity(...) computes the same weighted similarity for plain Python sequences.

If a future Polars release ships native methods with the same names, this package leaves the native implementation untouched.

Quick Examples

df = pl.DataFrame(
    {
        "a": [[1, 2, 3]],
        "b": [[2, 1, 3]],
        "groups": [[[1, 2, 3], [1, 2, 3], [4, 5, 6]]],
    }
)

df.with_columns(
    pl.col("a").list.similarity("b").alias("similarity"),
    pl.col("groups").list.mean_similarity().alias("mean_similarity"),
    pl.col("a").list.combinations().alias("pairs"),
    pl.col("a").list.zip("b", fields=["a", "b"]).alias("zipped"),
)

Development

make install
make develop
make test

Build and check the package locally:

make check-dist

Release steps are in docs/publishing.md.