Metadata-Version: 2.4
Name: planframe-polars
Version: 0.2.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.3.0,>=0.2.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(...)` with symmetric `on` or asymmetric `left_on` / `right_on`, plus optional `JoinOptions` mapped to Polars (`nulls_equal`, `validate`, `coalesce`, `maintain_order`, `allow_parallel` / streaming).
 
