planframe-polars 0.2.0

Polars backend adapter for PlanFrame.

planframe-polars

Polars adapter package for PlanFrame. Import as planframe_polars.

Usage

import polars as pl
from dataclasses import dataclass

from planframe_polars import PolarsFrame


@dataclass(frozen=True)
class UserSchema:
    id: int
    age: int


lf = pl.DataFrame({"id": [1], "age": [2]}).lazy()
class User(PolarsFrame):
    id: int
    age: int

pf = User(lf)
df = pf.select("id").collect()

# Or construct from python data:
pf2 = User({"id": [1], "age": [2]})

Execution model

PlanFrame is always lazy:

• Chaining methods (like .select(...)) does not run Polars operations.
• collect() evaluates the full plan. If the source is a polars.LazyFrame, this naturally compiles into a single lazy query before collecting.

Notes (Polars-specific)

• Pivot: LazyFrame.pivot(...) requires on_columns to be provided up-front (Polars must know the output schema prior to collect()). PlanFrame enforces this at execution time.
• concat_vertical: implemented via polars.concat(..., how="vertical").
• Join: implemented via LazyFrame.join(...) / DataFrame.join(...) with symmetric on or asymmetric left_on / right_on, plus optional JoinOptions mapped to Polars (nulls_equal, validate, coalesce, maintain_order, allow_parallel / streaming).