planframe-polars 0.1.0__tar.gz

planframe_polars-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+.env/
+
+# Packaging / build artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+pip-wheel-metadata/
+
+# Test / coverage artifacts
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Type check / lint caches
+.mypy_cache/
+.pyright/
+.ruff_cache/
+
+# Notebook checkpoints
+.ipynb_checkpoints/
+
+# IDE/editor settings
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db

planframe_polars-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 PlanFrame Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

planframe_polars-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: planframe-polars
+Version: 0.1.0
+Summary: Polars backend adapter for PlanFrame.
+Project-URL: Repository, https://github.com/eddiethedean/planframe
+Project-URL: Documentation, https://github.com/eddiethedean/planframe/blob/main/README.md
+Project-URL: Issues, https://github.com/eddiethedean/planframe/issues
+Author: PlanFrame Contributors
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: planframe<0.2.0,>=0.1.0
+Requires-Dist: polars>=0.20
+Description-Content-Type: text/markdown
+
+## planframe-polars
+
+Polars adapter package for PlanFrame. Import as `planframe_polars`.
+
+### Usage
+
+```python
+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(...)` using the provided `on`, `how`, and `suffix`.
+ 

planframe_polars-0.1.0/README.md

@@ -0,0 +1,43 @@
+## planframe-polars
+
+Polars adapter package for PlanFrame. Import as `planframe_polars`.
+
+### Usage
+
+```python
+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(...)` using the provided `on`, `how`, and `suffix`.
+ 

planframe_polars-0.1.0/planframe_polars/__init__.py

@@ -0,0 +1,7 @@
+from planframe_polars.adapter import PolarsAdapter
+from planframe_polars.frame import PolarsFrame
+
+__all__ = [
+    "PolarsAdapter",
+    "PolarsFrame",
+]

planframe_polars-0.1.0/planframe_polars/adapter.py

@@ -0,0 +1,442 @@
+from __future__ import annotations
+
+from typing import Any, Literal, cast
+
+import polars as pl
+
+from planframe.backend.adapter import BaseAdapter
+from planframe.expr.api import Expr
+from planframe_polars.compile_expr import compile_expr
+
+PolarsBackendFrame = pl.DataFrame | pl.LazyFrame
+
+
+class PolarsAdapter(BaseAdapter[PolarsBackendFrame, pl.Expr]):
+    name = "polars"
+
+    def _collect_df(self, df: PolarsBackendFrame) -> pl.DataFrame:
+        out = df.collect() if isinstance(df, pl.LazyFrame) else df
+        # Polars' type stubs may model `collect()` as returning an intermediate query.
+        if not isinstance(out, pl.DataFrame):
+            raise TypeError("Expected Polars collect() to return a DataFrame")
+        return out
+
+    def select(self, df: PolarsBackendFrame, columns: tuple[str, ...]) -> PolarsBackendFrame:
+        return df.select(list(columns))
+
+    def drop(self, df: PolarsBackendFrame, columns: tuple[str, ...]) -> PolarsBackendFrame:
+        return df.drop(list(columns))
+
+    def rename(self, df: PolarsBackendFrame, mapping: dict[str, str]) -> PolarsBackendFrame:
+        return df.rename(mapping)
+
+    def with_column(self, df: PolarsBackendFrame, name: str, expr: pl.Expr) -> PolarsBackendFrame:
+        return df.with_columns(expr.alias(name))
+
+    def cast(self, df: PolarsBackendFrame, name: str, dtype: Any) -> PolarsBackendFrame:
+        return df.with_columns(pl.col(name).cast(dtype))
+
+    def filter(self, df: PolarsBackendFrame, predicate: pl.Expr) -> PolarsBackendFrame:
+        return df.filter(predicate)
+
+    def sort(
+        self,
+        df: PolarsBackendFrame,
+        columns: tuple[str, ...],
+        *,
+        descending: bool = False,
+        nulls_last: bool = False,
+    ) -> PolarsBackendFrame:
+        if not columns:
+            return df
+        return df.sort(list(columns), descending=descending, nulls_last=nulls_last)
+
+    def unique(
+        self,
+        df: PolarsBackendFrame,
+        subset: tuple[str, ...] | None,
+        *,
+        keep: str = "first",
+        maintain_order: bool = False,
+    ) -> PolarsBackendFrame:
+        kwargs: dict[str, Any] = {"keep": keep, "maintain_order": maintain_order}
+        if subset is not None:
+            kwargs["subset"] = list(subset)
+        return df.unique(**kwargs)  # type: ignore[arg-type]
+
+    def duplicated(
+        self,
+        df: PolarsBackendFrame,
+        subset: tuple[str, ...] | None,
+        *,
+        keep: str | bool = "first",
+        out_name: str = "duplicated",
+    ) -> PolarsBackendFrame:
+        if keep is False:
+            raise NotImplementedError(
+                "duplicated(..., keep=False) is not supported in this adapter yet"
+            )
+        if keep not in {"first", "last"}:
+            raise ValueError("keep must be 'first', 'last', or False")
+
+        cols = list(subset) if subset is not None else None
+        expr = pl.struct(cols) if cols is not None else pl.struct(pl.all())
+        mask_expr = expr.is_duplicated()
+
+        if isinstance(df, pl.LazyFrame):
+            return df.select(mask_expr.alias(out_name))
+        mask = df.select(mask_expr.alias(out_name))[out_name]
+        return pl.DataFrame({out_name: mask})
+
+    def compile_expr(self, expr: Any) -> pl.Expr:
+        if not isinstance(expr, Expr):
+            raise TypeError(f"Expected PlanFrame Expr, got {type(expr)!r}")
+        return compile_expr(expr)
+
+    def group_by_agg(
+        self,
+        df: PolarsBackendFrame,
+        *,
+        keys: tuple[str, ...],
+        named_aggs: dict[str, tuple[str, str]],
+    ) -> PolarsBackendFrame:
+        if not keys:
+            raise ValueError("keys must be non-empty")
+        agg_exprs: list[pl.Expr] = []
+        for out_name, (op, col) in named_aggs.items():
+            e = pl.col(col)
+            if op == "count":
+                ex = e.count()
+            elif op == "sum":
+                ex = e.sum()
+            elif op == "mean":
+                ex = e.mean()
+            elif op == "min":
+                ex = e.min()
+            elif op == "max":
+                ex = e.max()
+            elif op == "n_unique":
+                ex = e.n_unique()
+            else:
+                raise ValueError(f"Unsupported agg op: {op!r}")
+            agg_exprs.append(ex.alias(out_name))
+        return df.group_by(list(keys)).agg(agg_exprs)
+
+    def drop_nulls(
+        self, df: PolarsBackendFrame, subset: tuple[str, ...] | None
+    ) -> PolarsBackendFrame:
+        if subset is None:
+            return df.drop_nulls()
+        return df.drop_nulls(list(subset))
+
+    def fill_null(
+        self, df: PolarsBackendFrame, value: Any, subset: tuple[str, ...] | None
+    ) -> PolarsBackendFrame:
+        if subset is None:
+            return df.fill_null(value)
+        exprs = [pl.col(c).fill_null(value) for c in subset]
+        return df.with_columns(exprs)
+
+    def melt(
+        self,
+        df: PolarsBackendFrame,
+        *,
+        id_vars: tuple[str, ...],
+        value_vars: tuple[str, ...],
+        variable_name: str,
+        value_name: str,
+    ) -> PolarsBackendFrame:
+        # Prefer unpivot (polars deprecates melt on LazyFrame).
+        return df.unpivot(
+            index=list(id_vars),
+            on=list(value_vars),
+            variable_name=variable_name,
+            value_name=value_name,
+        )
+
+    def join(
+        self,
+        left: PolarsBackendFrame,
+        right: PolarsBackendFrame,
+        *,
+        on: tuple[str, ...],
+        how: str = "inner",
+        suffix: str = "_right",
+    ) -> PolarsBackendFrame:
+        if not on:
+            raise ValueError("on must be non-empty")
+        allowed_how = {
+            "inner",
+            "left",
+            "right",
+            "full",
+            "semi",
+            "anti",
+            "cross",
+        }
+        if how not in allowed_how:
+            raise ValueError(f"Unsupported join how={how!r}")
+
+        # Keep plans always-lazy: coerce eager frames to LazyFrame.
+        left_lf = left.lazy() if isinstance(left, pl.DataFrame) else left
+        right_lf = right.lazy() if isinstance(right, pl.DataFrame) else right
+
+        how_lit = cast(
+            Literal["inner", "left", "right", "full", "semi", "anti", "cross"],
+            how,
+        )
+        return left_lf.join(right_lf, on=list(on), how=how_lit, suffix=suffix)
+
+    def slice(
+        self, df: PolarsBackendFrame, *, offset: int, length: int | None
+    ) -> PolarsBackendFrame:
+        return df.slice(offset, length)
+
+    def head(self, df: PolarsBackendFrame, n: int) -> PolarsBackendFrame:
+        return df.head(n)
+
+    def tail(self, df: PolarsBackendFrame, n: int) -> PolarsBackendFrame:
+        return df.tail(n)
+
+    def concat_vertical(
+        self, left: PolarsBackendFrame, right: PolarsBackendFrame
+    ) -> PolarsBackendFrame:
+        return pl.concat([left, right], how="vertical")
+
+    def concat_horizontal(
+        self, left: PolarsBackendFrame, right: PolarsBackendFrame
+    ) -> PolarsBackendFrame:
+        return pl.concat([left, right], how="horizontal")
+
+    def pivot(
+        self,
+        df: PolarsBackendFrame,
+        *,
+        index: tuple[str, ...],
+        on: str,
+        values: str,
+        agg: str = "first",
+        on_columns: tuple[str, ...] | None = None,
+        separator: str = "_",
+    ) -> PolarsBackendFrame:
+        allowed_agg = {
+            "min",
+            "max",
+            "first",
+            "last",
+            "sum",
+            "mean",
+            "median",
+            "len",  # polars name for "count" in pivot
+            "count",
+            "n_unique",
+        }
+        if agg not in allowed_agg:
+            raise ValueError(f"Unsupported pivot agg={agg!r}")
+        if agg == "count":
+            agg_arg: Literal[
+                "min",
+                "max",
+                "first",
+                "last",
+                "sum",
+                "mean",
+                "median",
+                "len",
+            ] | pl.Expr = "len"
+        elif agg == "n_unique":
+            agg_arg = pl.col(values).n_unique()
+        else:
+            agg_arg = cast(
+                Literal[
+                    "min",
+                    "max",
+                    "first",
+                    "last",
+                    "sum",
+                    "mean",
+                    "median",
+                    "len",
+                ],
+                agg,
+            )
+
+        if isinstance(df, pl.LazyFrame):
+            if on_columns is None:
+                raise ValueError("Lazy pivot requires on_columns to be provided")
+            return df.pivot(
+                index=list(index),
+                on=on,
+                values=values,
+                aggregate_function=agg_arg,
+                on_columns=list(on_columns),
+                separator=separator,
+            )
+
+        return df.pivot(
+            index=list(index),
+            on=on,
+            values=values,
+            aggregate_function=agg_arg,
+            on_columns=list(on_columns) if on_columns is not None else None,
+            separator=separator,
+        )
+
+    def write_parquet(
+        self,
+        df: PolarsBackendFrame,
+        path: str,
+        *,
+        compression: str = "zstd",
+        row_group_size: int | None = None,
+        partition_by: tuple[str, ...] | None = None,
+        storage_options: dict[str, Any] | None = None,
+    ) -> None:
+        out = self._collect_df(df)
+        if compression not in {"uncompressed", "snappy", "gzip", "brotli", "zstd", "lz4"}:
+            raise ValueError(f"Unsupported parquet compression={compression!r}")
+        comp_lit = cast(
+            Literal["uncompressed", "snappy", "gzip", "brotli", "zstd", "lz4"],
+            compression,
+        )
+        out.write_parquet(
+            path,
+            compression=comp_lit,
+            row_group_size=row_group_size,
+            partition_by=list(partition_by) if partition_by is not None else None,
+            storage_options=storage_options,
+        )
+
+    def write_csv(
+        self,
+        df: PolarsBackendFrame,
+        path: str,
+        *,
+        separator: str = ",",
+        include_header: bool = True,
+        storage_options: dict[str, Any] | None = None,
+    ) -> None:
+        out = self._collect_df(df)
+        out.write_csv(
+            path,
+            separator=separator,
+            include_header=include_header,
+            storage_options=storage_options,
+        )
+
+    def write_ndjson(
+        self, df: PolarsBackendFrame, path: str, *, storage_options: dict[str, Any] | None = None
+    ) -> None:
+        out = self._collect_df(df)
+        # Polars write_ndjson does not currently accept storage_options.
+        # The path may still be a cloud URI if the Polars build supports it implicitly.
+        out.write_ndjson(path)
+
+    def write_ipc(
+        self,
+        df: PolarsBackendFrame,
+        path: str,
+        *,
+        compression: str = "uncompressed",
+        storage_options: dict[str, Any] | None = None,
+    ) -> None:
+        out = self._collect_df(df)
+        if compression not in {"uncompressed", "lz4", "zstd"}:
+            raise ValueError(f"Unsupported ipc compression={compression!r}")
+        comp_lit = cast(Literal["uncompressed", "lz4", "zstd"], compression)
+        # Polars write_ipc does not currently accept storage_options.
+        out.write_ipc(path, compression=comp_lit)
+
+    def write_database(
+        self,
+        df: PolarsBackendFrame,
+        *,
+        table_name: str,
+        connection: Any,
+        if_table_exists: str = "fail",
+        engine: str | None = None,
+    ) -> None:
+        out = self._collect_df(df)
+        kwargs: dict[str, Any] = {"if_table_exists": if_table_exists}
+        if engine is not None:
+            kwargs["engine"] = engine
+        out.write_database(table_name=table_name, connection=connection, **kwargs)
+
+    def write_excel(self, df: PolarsBackendFrame, path: str, *, worksheet: str = "Sheet1") -> None:
+        out = self._collect_df(df)
+        out.write_excel(workbook=path, worksheet=worksheet)
+
+    def write_delta(
+        self,
+        df: PolarsBackendFrame,
+        target: str,
+        *,
+        mode: str = "error",
+        storage_options: dict[str, Any] | None = None,
+    ) -> None:
+        out = self._collect_df(df)
+        if mode not in {"error", "append", "overwrite", "ignore"}:
+            raise ValueError(f"Unsupported delta mode={mode!r}")
+        mode_lit = cast(Literal["error", "append", "overwrite", "ignore"], mode)
+        out.write_delta(target, mode=mode_lit, storage_options=storage_options)
+
+    def write_avro(
+        self,
+        df: PolarsBackendFrame,
+        path: str,
+        *,
+        compression: str = "uncompressed",
+        name: str = "",
+    ) -> None:
+        out = self._collect_df(df)
+        if compression not in {"uncompressed", "snappy", "deflate"}:
+            raise ValueError(f"Unsupported avro compression={compression!r}")
+        comp_lit = cast(Literal["uncompressed", "snappy", "deflate"], compression)
+        out.write_avro(path, compression=comp_lit, name=name)
+
+    def explode(self, df: PolarsBackendFrame, column: str) -> PolarsBackendFrame:
+        return df.explode(column)
+
+    def unnest(self, df: PolarsBackendFrame, column: str) -> PolarsBackendFrame:
+        return df.unnest(column)
+
+    def drop_nulls_all(
+        self, df: PolarsBackendFrame, subset: tuple[str, ...] | None
+    ) -> PolarsBackendFrame:
+        if subset is None:
+            # Drop rows where *all* columns are null.
+            return df.filter(~pl.all_horizontal(pl.all().is_null()))
+        cols = list(subset)
+        if not cols:
+            return df
+        mask = pl.all_horizontal([pl.col(c).is_null() for c in cols])
+        return df.filter(~mask)
+
+    def sample(
+        self,
+        df: PolarsBackendFrame,
+        *,
+        n: int | None = None,
+        frac: float | None = None,
+        with_replacement: bool = False,
+        shuffle: bool = False,
+        seed: int | None = None,
+    ) -> PolarsBackendFrame:
+        df2 = self._collect_df(df)
+        kwargs: dict[str, Any] = {
+            "with_replacement": with_replacement,
+            "shuffle": shuffle,
+            "seed": seed,
+        }
+        if n is not None:
+            return df2.sample(n=n, **kwargs)
+        return df2.sample(fraction=frac, **kwargs)
+
+    def collect(self, df: PolarsBackendFrame) -> PolarsBackendFrame:
+        return self._collect_df(df) if isinstance(df, pl.LazyFrame) else df
+
+    def to_dicts(self, df: PolarsBackendFrame) -> list[dict[str, object]]:
+        return self._collect_df(df).to_dicts()
+
+    def to_dict(self, df: PolarsBackendFrame) -> dict[str, list[object]]:
+        return self._collect_df(df).to_dict(as_series=False)  # type: ignore[return-value]

planframe_polars-0.1.0/planframe_polars/compile_expr.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from typing import Any, Literal, cast
+
+import polars as pl
+
+from planframe.backend.errors import PlanFrameExpressionError
+from planframe.expr.api import (
+    Add,
+    And,
+    Abs,
+    Between,
+    Ceil,
+    Col,
+    Coalesce,
+    Clip,
+    DtDay,
+    DtMonth,
+    DtYear,
+    Eq,
+    Exp,
+    Expr,
+    Floor,
+    Ge,
+    Gt,
+    IfElse,
+    IsIn,
+    IsNotNull,
+    IsNull,
+    Log,
+    Le,
+    Lit,
+    Lt,
+    Mul,
+    Ne,
+    Not,
+    Over,
+    Or,
+    Pow,
+    Round,
+    StrContains,
+    StrEndsWith,
+    StrLen,
+    StrLower,
+    StrReplace,
+    StrSplit,
+    StrStrip,
+    StrStartsWith,
+    StrUpper,
+    Sub,
+    Sqrt,
+    TrueDiv,
+    IsFinite,
+    Xor,
+)
+
+
+def compile_expr(expr: Expr[Any]) -> pl.Expr:
+    if isinstance(expr, Col):
+        return pl.col(expr.name)
+    if isinstance(expr, Lit):
+        return pl.lit(expr.value)
+    if isinstance(expr, Add):
+        return compile_expr(expr.left) + compile_expr(expr.right)
+    if isinstance(expr, Sub):
+        return compile_expr(expr.left) - compile_expr(expr.right)
+    if isinstance(expr, Mul):
+        return compile_expr(expr.left) * compile_expr(expr.right)
+    if isinstance(expr, TrueDiv):
+        return compile_expr(expr.left) / compile_expr(expr.right)
+    if isinstance(expr, Eq):
+        return compile_expr(expr.left) == compile_expr(expr.right)
+    if isinstance(expr, Ne):
+        return compile_expr(expr.left) != compile_expr(expr.right)
+    if isinstance(expr, Lt):
+        return compile_expr(expr.left) < compile_expr(expr.right)
+    if isinstance(expr, Le):
+        return compile_expr(expr.left) <= compile_expr(expr.right)
+    if isinstance(expr, Gt):
+        return compile_expr(expr.left) > compile_expr(expr.right)
+    if isinstance(expr, Ge):
+        return compile_expr(expr.left) >= compile_expr(expr.right)
+    if isinstance(expr, IsNull):
+        return compile_expr(expr.value).is_null()
+    if isinstance(expr, IsNotNull):
+        return compile_expr(expr.value).is_not_null()
+    if isinstance(expr, IsIn):
+        return compile_expr(expr.value).is_in(list(expr.options))
+    if isinstance(expr, And):
+        return compile_expr(expr.left) & compile_expr(expr.right)
+    if isinstance(expr, Or):
+        return compile_expr(expr.left) | compile_expr(expr.right)
+    if isinstance(expr, Not):
+        return ~compile_expr(expr.value)
+    if isinstance(expr, Xor):
+        return compile_expr(expr.left) ^ compile_expr(expr.right)
+    if isinstance(expr, Abs):
+        return compile_expr(expr.value).abs()
+    if isinstance(expr, Round):
+        e = compile_expr(expr.value)
+        return e.round(expr.ndigits) if expr.ndigits is not None else e.round()
+    if isinstance(expr, Floor):
+        return compile_expr(expr.value).floor()
+    if isinstance(expr, Ceil):
+        return compile_expr(expr.value).ceil()
+    if isinstance(expr, Coalesce):
+        return pl.coalesce([compile_expr(v) for v in expr.values])
+    if isinstance(expr, IfElse):
+        return (
+            pl.when(compile_expr(expr.cond))
+            .then(compile_expr(expr.then_value))
+            .otherwise(compile_expr(expr.else_value))
+        )
+    if isinstance(expr, Over):
+        e = compile_expr(expr.value)
+        return e.over(
+            partition_by=list(expr.partition_by),
+            order_by=(list(expr.order_by) if expr.order_by is not None else None),
+        )
+    if isinstance(expr, Between):
+        allowed_closed = {"left", "right", "both", "none"}
+        if expr.closed not in allowed_closed:
+            raise ValueError(f"Unsupported closed interval: {expr.closed!r}")
+        closed_lit = cast(Literal["left", "right", "both", "none"], expr.closed)
+        return compile_expr(expr.value).is_between(
+            compile_expr(expr.low),
+            compile_expr(expr.high),
+            closed=closed_lit,
+        )
+    if isinstance(expr, Clip):
+        e = compile_expr(expr.value)
+        lower = compile_expr(expr.lower) if expr.lower is not None else None
+        upper = compile_expr(expr.upper) if expr.upper is not None else None
+        return e.clip(lower_bound=lower, upper_bound=upper)
+    if isinstance(expr, Pow):
+        return compile_expr(expr.base) ** compile_expr(expr.exponent)
+    if isinstance(expr, Exp):
+        return compile_expr(expr.value).exp()
+    if isinstance(expr, Log):
+        return compile_expr(expr.value).log()
+    if isinstance(expr, StrContains):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.contains(expr.pattern, literal=expr.literal)
+    if isinstance(expr, StrStartsWith):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.starts_with(expr.prefix)
+    if isinstance(expr, StrEndsWith):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.ends_with(expr.suffix)
+    if isinstance(expr, StrLower):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.to_lowercase()
+    if isinstance(expr, StrUpper):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.to_uppercase()
+    if isinstance(expr, StrLen):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.len_chars()
+    if isinstance(expr, StrReplace):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.replace_all(expr.pattern, expr.replacement, literal=expr.literal)
+    if isinstance(expr, StrStrip):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.strip_chars()
+    if isinstance(expr, StrSplit):
+        e = compile_expr(expr.value).cast(pl.Utf8)
+        return e.str.split(expr.by)
+    if isinstance(expr, DtYear):
+        return compile_expr(expr.value).dt.year()
+    if isinstance(expr, DtMonth):
+        return compile_expr(expr.value).dt.month()
+    if isinstance(expr, DtDay):
+        return compile_expr(expr.value).dt.day()
+    if isinstance(expr, Sqrt):
+        return compile_expr(expr.value).sqrt()
+    if isinstance(expr, IsFinite):
+        return compile_expr(expr.value).is_finite()
+
+    raise PlanFrameExpressionError(f"Unsupported expr node: {type(expr)!r}")

planframe_polars-0.1.0/planframe_polars/frame.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, ClassVar, Generic, Literal, TypeVar, cast
+
+import polars as pl
+
+from planframe.frame import Frame
+from planframe_polars.adapter import PolarsAdapter, PolarsBackendFrame
+
+SchemaT = TypeVar("SchemaT")
+
+PolarsData = Mapping[str, Sequence[object]] | Sequence[Mapping[str, object]]
+
+
+def _schema_defaults(schema: type[Any]) -> dict[str, object]:
+    ann = dict(getattr(schema, "__dict__", {}).get("__annotations__", {}))
+    out: dict[str, object] = {}
+    for name in ann.keys():
+        if name in getattr(schema, "__dict__", {}):
+            out[name] = getattr(schema, name)
+    return out
+
+
+def _fill_missing_from_defaults(data: PolarsData, *, defaults: dict[str, object]) -> PolarsData:
+    if not defaults:
+        return data
+
+    if isinstance(data, Mapping):
+        data_map = cast(Mapping[str, Sequence[object]], data)
+        if not data_map:
+            return dict(data_map)
+        # Infer row count from the first column.
+        first = next(iter(data_map.values()))
+        n = len(first)
+        out: dict[str, list[object]] = {k: list(v) for k, v in data_map.items()}
+        for k, dv in defaults.items():
+            if k not in out:
+                out[k] = [dv] * n
+        return out
+
+    # list-of-dicts
+    out_rows: list[dict[str, object]] = []
+    for row in data:
+        r = dict(row)
+        for k, dv in defaults.items():
+            if k not in r:
+                r[k] = dv
+        out_rows.append(r)
+    return out_rows
+
+
+def _to_polars_backend_frame(
+    data: PolarsData, *, schema: type[Any], lazy: bool
+) -> PolarsBackendFrame:
+    defaults = _schema_defaults(schema)
+    data2 = _fill_missing_from_defaults(data, defaults=defaults)
+    df = pl.DataFrame(data2)  # type: ignore[arg-type]
+    return df.lazy() if lazy else df
+
+
+class _PolarsFrameMeta(type):
+    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
+        # Allow normal dataclass construction when `Frame.source(...)` calls `cls(_data=..., ...)`.
+        if "_data" in kwargs and "_adapter" in kwargs and "_plan" in kwargs and "_schema" in kwargs:
+            return super().__call__(*args, **kwargs)
+
+        data = args[0] if args else kwargs.pop("data")
+        if isinstance(data, (pl.DataFrame, pl.LazyFrame)):
+            raise TypeError(
+                "PolarsFrame constructors accept only Python data (dict-of-lists or list-of-dicts). "
+                "Use `Frame.source(...)` for advanced usage."
+            )
+        lazy = kwargs.pop("lazy", True)
+        if kwargs:
+            raise TypeError(f"Unexpected constructor kwargs: {sorted(kwargs)}")
+        df = _to_polars_backend_frame(data, schema=cls, lazy=lazy)
+        return PolarsFrame.source(
+            df,
+            adapter=PolarsFrame._adapter_singleton,
+            schema=cast(type[SchemaT], cls),
+        )
+
+
+class PolarsFrame(
+    Frame[SchemaT, PolarsBackendFrame, pl.Expr], Generic[SchemaT], metaclass=_PolarsFrameMeta
+):
+    """A PlanFrame `Frame` bound to the Polars backend."""
+
+    _adapter_singleton: ClassVar[PolarsAdapter] = PolarsAdapter()
+    __planframe_model__ = True
+
+    @classmethod
+    def scan_parquet(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        hive_partitioning: bool | None = None,
+        storage_options: dict[str, Any] | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        kwargs: dict[str, Any] = {"storage_options": storage_options}
+        if hive_partitioning is not None:
+            kwargs["hive_partitioning"] = hive_partitioning
+        lf = pl.scan_parquet(path, **kwargs)
+        return cls.source(lf, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def scan_parquet_dataset(
+        cls,
+        path_or_glob: str,
+        *,
+        schema: type[SchemaT],
+        storage_options: dict[str, Any] | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        return cls.scan_parquet(
+            path_or_glob,
+            schema=schema,
+            hive_partitioning=True,
+            storage_options=storage_options,
+        )
+
+    @classmethod
+    def scan_csv(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        storage_options: dict[str, Any] | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        lf = pl.scan_csv(path, storage_options=storage_options)
+        return cls.source(lf, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def scan_ndjson(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        storage_options: dict[str, Any] | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        lf = pl.scan_ndjson(path, storage_options=storage_options)
+        return cls.source(lf, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def scan_ipc(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        hive_partitioning: bool | None = None,
+        storage_options: dict[str, Any] | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        kwargs: dict[str, Any] = {"storage_options": storage_options}
+        if hive_partitioning is not None:
+            kwargs["hive_partitioning"] = hive_partitioning
+        lf = pl.scan_ipc(path, **kwargs)
+        return cls.source(lf, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def scan_delta(
+        cls,
+        source: str,
+        *,
+        schema: type[SchemaT],
+        version: int | str | None = None,
+        storage_options: dict[str, Any] | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        kwargs: dict[str, Any] = {"storage_options": storage_options}
+        if version is not None:
+            kwargs["version"] = version
+        lf = pl.scan_delta(source, **kwargs)
+        return cls.source(lf, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def read_delta(
+        cls,
+        source: str,
+        *,
+        schema: type[SchemaT],
+        version: int | str | None = None,
+        storage_options: dict[str, Any] | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        kwargs: dict[str, Any] = {"storage_options": storage_options}
+        if version is not None:
+            kwargs["version"] = version
+        df = pl.read_delta(source, **kwargs)
+        return cls.source(df, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def read_excel(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        sheet_name: str | None = None,
+    ) -> PolarsFrame[SchemaT]:
+        kwargs: dict[str, Any] = {}
+        if sheet_name is not None:
+            kwargs["sheet_name"] = sheet_name
+        df = pl.read_excel(path, **kwargs)
+        return cls.source(df, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def read_avro(cls, path: str, *, schema: type[SchemaT]) -> PolarsFrame[SchemaT]:
+        df = pl.read_avro(path)
+        return cls.source(df, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def read_database(
+        cls, query: str, *, connection: Any, schema: type[SchemaT]
+    ) -> PolarsFrame[SchemaT]:
+        df = pl.read_database(query=query, connection=connection)
+        return cls.source(df, adapter=cls._adapter_singleton, schema=schema)
+
+    @classmethod
+    def read_database_uri(
+        cls,
+        query: str,
+        *,
+        uri: str,
+        engine: Literal["connectorx", "adbc"] | None = None,
+        schema: type[SchemaT],
+    ) -> PolarsFrame[SchemaT]:
+        kwargs: dict[str, Any] = {}
+        if engine is not None:
+            kwargs["engine"] = engine
+        df = pl.read_database_uri(query=query, uri=uri, **kwargs)
+        return cls.source(df, adapter=cls._adapter_singleton, schema=schema)

planframe_polars-0.1.0/planframe_polars/frame.pyi

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal, TypeVar
+
+import polars as pl
+
+from planframe.frame import Frame
+
+SchemaT = TypeVar("SchemaT")
+
+PolarsBackendFrame = pl.DataFrame | pl.LazyFrame
+
+class PolarsFrame(Frame[Any, PolarsBackendFrame, pl.Expr]):
+    def __new__(
+        cls,
+        data: Mapping[str, Sequence[object]] | Sequence[Mapping[str, object]],
+        *,
+        lazy: bool = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def scan_parquet(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        hive_partitioning: bool | None = ...,
+        storage_options: dict[str, Any] | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def scan_parquet_dataset(
+        cls,
+        path_or_glob: str,
+        *,
+        schema: type[SchemaT],
+        storage_options: dict[str, Any] | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def scan_csv(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        storage_options: dict[str, Any] | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def scan_ndjson(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        storage_options: dict[str, Any] | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def scan_ipc(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        hive_partitioning: bool | None = ...,
+        storage_options: dict[str, Any] | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def scan_delta(
+        cls,
+        source: str,
+        *,
+        schema: type[SchemaT],
+        version: int | str | None = ...,
+        storage_options: dict[str, Any] | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def read_delta(
+        cls,
+        source: str,
+        *,
+        schema: type[SchemaT],
+        version: int | str | None = ...,
+        storage_options: dict[str, Any] | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def read_excel(
+        cls,
+        path: str,
+        *,
+        schema: type[SchemaT],
+        sheet_name: str | None = ...,
+    ) -> PolarsFrame: ...
+    @classmethod
+    def read_avro(cls, path: str, *, schema: type[SchemaT]) -> PolarsFrame: ...
+    @classmethod
+    def read_database(
+        cls, query: str, *, connection: Any, schema: type[SchemaT]
+    ) -> PolarsFrame: ...
+    @classmethod
+    def read_database_uri(
+        cls,
+        query: str,
+        *,
+        uri: str,
+        engine: Literal["connectorx", "adbc"] | None = ...,
+        schema: type[SchemaT],
+    ) -> PolarsFrame: ...

planframe_polars-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+ [build-system]
+ requires = ["hatchling>=1.25"]
+ build-backend = "hatchling.build"
+ 
+ [project]
+ name = "planframe-polars"
+ version = "0.1.0"
+ description = "Polars backend adapter for PlanFrame."
+ readme = "README.md"
+ requires-python = ">=3.10"
+ license = { text = "MIT" }
+ authors = [{ name = "PlanFrame Contributors" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "License :: OSI Approved :: MIT License",
+  "Typing :: Typed",
+]
+ dependencies = [
+ "planframe>=0.1.0,<0.2.0",
+   "polars>=0.20",
+ ]
+ 
+ [project.urls]
+Repository = "https://github.com/eddiethedean/planframe"
+Documentation = "https://github.com/eddiethedean/planframe/blob/main/README.md"
+Issues = "https://github.com/eddiethedean/planframe/issues"
+ 
+ [tool.hatch.build.targets.wheel]
+ packages = ["planframe_polars"]
+