planframe 0.1.0__tar.gz

planframe-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-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-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: planframe
+Version: 0.1.0
+Summary: Core typed relational planning layer for Python DataFrames.
+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: pydantic>=1.10
+Requires-Dist: typing-extensions>=4.8
+Description-Content-Type: text/markdown
+
+## planframe
+
+Core package for PlanFrame (typed planning layer). Import as `planframe`.
+
+### What you get
+- `planframe.Frame`: immutable, schema-aware transformation plan (**always lazy**)
+- `planframe.expr`: typed expression IR (`col`, `lit`, arithmetic/compare/boolean ops, `coalesce`, `if_else`, etc.)
+- `planframe.schema`: schema reflection (dataclass + Pydantic) and materialization
+
+### Note on backends
+`planframe` is backend-agnostic. It does not execute anything until `collect()` (even for eager backends). To execute plans you need an adapter package (e.g. `planframe-polars`).
+
+### Typing
+PlanFrame includes `py.typed` plus generated stubs (notably `planframe/frame.pyi`) to improve static typing in editors and Pyright.
+
+If you modify the `Frame` API, regenerate stubs from the repo root:
+
+```bash
+python scripts/generate_typing_stubs.py
+python scripts/generate_typing_stubs.py --check
+```
+ 

planframe-0.1.0/README.md

@@ -0,0 +1,22 @@
+## planframe
+
+Core package for PlanFrame (typed planning layer). Import as `planframe`.
+
+### What you get
+- `planframe.Frame`: immutable, schema-aware transformation plan (**always lazy**)
+- `planframe.expr`: typed expression IR (`col`, `lit`, arithmetic/compare/boolean ops, `coalesce`, `if_else`, etc.)
+- `planframe.schema`: schema reflection (dataclass + Pydantic) and materialization
+
+### Note on backends
+`planframe` is backend-agnostic. It does not execute anything until `collect()` (even for eager backends). To execute plans you need an adapter package (e.g. `planframe-polars`).
+
+### Typing
+PlanFrame includes `py.typed` plus generated stubs (notably `planframe/frame.pyi`) to improve static typing in editors and Pyright.
+
+If you modify the `Frame` API, regenerate stubs from the repo root:
+
+```bash
+python scripts/generate_typing_stubs.py
+python scripts/generate_typing_stubs.py --check
+```
+ 

planframe-0.1.0/planframe/__init__.py

@@ -0,0 +1,4 @@
+from planframe.frame import Frame
+from planframe.schema.ir import Schema
+
+__all__ = ["Frame", "Schema"]

planframe-0.1.0/planframe/backend/__init__.py

@@ -0,0 +1,18 @@
+from planframe.backend.adapter import BackendAdapter, BaseAdapter
+from planframe.backend.errors import (
+    PlanFrameBackendError,
+    PlanFrameError,
+    PlanFrameExecutionError,
+    PlanFrameExpressionError,
+    PlanFrameSchemaError,
+)
+
+__all__ = [
+    "BackendAdapter",
+    "BaseAdapter",
+    "PlanFrameError",
+    "PlanFrameBackendError",
+    "PlanFrameExecutionError",
+    "PlanFrameExpressionError",
+    "PlanFrameSchemaError",
+]

planframe-0.1.0/planframe/backend/adapter.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+BackendFrameT = TypeVar("BackendFrameT")
+BackendExprT = TypeVar("BackendExprT")
+
+
+class BaseAdapter(ABC, Generic[BackendFrameT, BackendExprT]):
+    """Backend execution base class.
+
+    Core PlanFrame code must not import backend libraries. Adapters translate PlanFrame
+    operations + expression IR into backend-native operations.
+    """
+
+    name: str
+
+    @abstractmethod
+    def select(self, df: BackendFrameT, columns: tuple[str, ...]) -> BackendFrameT: ...
+
+    @abstractmethod
+    def drop(self, df: BackendFrameT, columns: tuple[str, ...]) -> BackendFrameT: ...
+
+    @abstractmethod
+    def rename(self, df: BackendFrameT, mapping: dict[str, str]) -> BackendFrameT: ...
+
+    @abstractmethod
+    def with_column(self, df: BackendFrameT, name: str, expr: BackendExprT) -> BackendFrameT: ...
+
+    @abstractmethod
+    def cast(self, df: BackendFrameT, name: str, dtype: Any) -> BackendFrameT: ...
+
+    @abstractmethod
+    def filter(self, df: BackendFrameT, predicate: BackendExprT) -> BackendFrameT: ...
+
+    @abstractmethod
+    def sort(
+        self,
+        df: BackendFrameT,
+        columns: tuple[str, ...],
+        *,
+        descending: bool = False,
+        nulls_last: bool = False,
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def unique(
+        self,
+        df: BackendFrameT,
+        subset: tuple[str, ...] | None,
+        *,
+        keep: str = "first",
+        maintain_order: bool = False,
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def duplicated(
+        self,
+        df: BackendFrameT,
+        subset: tuple[str, ...] | None,
+        *,
+        keep: str | bool = "first",
+        out_name: str = "duplicated",
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def group_by_agg(
+        self,
+        df: BackendFrameT,
+        *,
+        keys: tuple[str, ...],
+        named_aggs: dict[str, tuple[str, str]],
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def drop_nulls(
+        self,
+        df: BackendFrameT,
+        subset: tuple[str, ...] | None,
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def fill_null(
+        self,
+        df: BackendFrameT,
+        value: Any,
+        subset: tuple[str, ...] | None,
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def melt(
+        self,
+        df: BackendFrameT,
+        *,
+        id_vars: tuple[str, ...],
+        value_vars: tuple[str, ...],
+        variable_name: str,
+        value_name: str,
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def join(
+        self,
+        left: BackendFrameT,
+        right: BackendFrameT,
+        *,
+        on: tuple[str, ...],
+        how: str = "inner",
+        suffix: str = "_right",
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def slice(
+        self,
+        df: BackendFrameT,
+        *,
+        offset: int,
+        length: int | None,
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def head(self, df: BackendFrameT, n: int) -> BackendFrameT: ...
+
+    @abstractmethod
+    def tail(self, df: BackendFrameT, n: int) -> BackendFrameT: ...
+
+    @abstractmethod
+    def concat_vertical(self, left: BackendFrameT, right: BackendFrameT) -> BackendFrameT: ...
+
+    @abstractmethod
+    def concat_horizontal(self, left: BackendFrameT, right: BackendFrameT) -> BackendFrameT: ...
+
+    @abstractmethod
+    def pivot(
+        self,
+        df: BackendFrameT,
+        *,
+        index: tuple[str, ...],
+        on: str,
+        values: str,
+        agg: str = "first",
+        on_columns: tuple[str, ...] | None = None,
+        separator: str = "_",
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def write_parquet(
+        self,
+        df: BackendFrameT,
+        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: ...
+
+    @abstractmethod
+    def write_csv(
+        self,
+        df: BackendFrameT,
+        path: str,
+        *,
+        separator: str = ",",
+        include_header: bool = True,
+        storage_options: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    @abstractmethod
+    def write_ndjson(
+        self, df: BackendFrameT, path: str, *, storage_options: dict[str, Any] | None = None
+    ) -> None: ...
+
+    @abstractmethod
+    def write_ipc(
+        self,
+        df: BackendFrameT,
+        path: str,
+        *,
+        compression: str = "uncompressed",
+        storage_options: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    @abstractmethod
+    def write_database(
+        self,
+        df: BackendFrameT,
+        *,
+        table_name: str,
+        connection: Any,
+        if_table_exists: str = "fail",
+        engine: str | None = None,
+    ) -> None: ...
+
+    @abstractmethod
+    def write_excel(self, df: BackendFrameT, path: str, *, worksheet: str = "Sheet1") -> None: ...
+
+    @abstractmethod
+    def write_delta(
+        self,
+        df: BackendFrameT,
+        target: str,
+        *,
+        mode: str = "error",
+        storage_options: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    @abstractmethod
+    def write_avro(
+        self,
+        df: BackendFrameT,
+        path: str,
+        *,
+        compression: str = "uncompressed",
+        name: str = "",
+    ) -> None: ...
+
+    @abstractmethod
+    def explode(self, df: BackendFrameT, column: str) -> BackendFrameT: ...
+
+    @abstractmethod
+    def unnest(self, df: BackendFrameT, column: str) -> BackendFrameT: ...
+
+    @abstractmethod
+    def drop_nulls_all(
+        self, df: BackendFrameT, subset: tuple[str, ...] | None
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def sample(
+        self,
+        df: BackendFrameT,
+        *,
+        n: int | None = None,
+        frac: float | None = None,
+        with_replacement: bool = False,
+        shuffle: bool = False,
+        seed: int | None = None,
+    ) -> BackendFrameT: ...
+
+    @abstractmethod
+    def compile_expr(self, expr: Any) -> BackendExprT: ...
+
+    @abstractmethod
+    def collect(self, df: BackendFrameT) -> BackendFrameT: ...
+
+    @abstractmethod
+    def to_dicts(self, df: BackendFrameT) -> list[dict[str, object]]: ...
+
+    @abstractmethod
+    def to_dict(self, df: BackendFrameT) -> dict[str, list[object]]: ...
+
+
+# Backwards-compatible name for older imports.
+BackendAdapter = BaseAdapter

planframe-0.1.0/planframe/backend/errors.py

@@ -0,0 +1,18 @@
+class PlanFrameError(Exception):
+    """Base exception for PlanFrame."""
+
+
+class PlanFrameSchemaError(PlanFrameError):
+    """Raised when schema inference/evolution fails."""
+
+
+class PlanFrameExpressionError(PlanFrameError):
+    """Raised when expression typing/compilation fails."""
+
+
+class PlanFrameBackendError(PlanFrameError):
+    """Raised when a backend adapter fails or is misused."""
+
+
+class PlanFrameExecutionError(PlanFrameBackendError):
+    """Raised when backend execution/collection fails."""

planframe-0.1.0/planframe/expr/__init__.py

@@ -0,0 +1,99 @@
+from planframe.expr.api import (
+    Expr,
+    add,
+    abs_,
+    and_,
+    between,
+    ceil,
+    col,
+    contains,
+    coalesce,
+    day,
+    eq,
+    ends_with,
+    floor,
+    ge,
+    gt,
+    if_else,
+    infer_dtype,
+    is_not_null,
+    is_null,
+    isin,
+    length,
+    le,
+    lit,
+    lt,
+    log,
+    mul,
+    month,
+    ne,
+    not_,
+    or_,
+    over,
+    pow_,
+    replace,
+    strip,
+    split,
+    round_,
+    starts_with,
+    sub,
+    truediv,
+    upper,
+    lower,
+    year,
+    exp,
+    clip,
+    xor,
+    sqrt,
+    is_finite,
+)
+
+__all__ = [
+    "Expr",
+    "add",
+    "abs_",
+    "and_",
+    "between",
+    "ceil",
+    "col",
+    "contains",
+    "coalesce",
+    "day",
+    "eq",
+    "ends_with",
+    "floor",
+    "ge",
+    "gt",
+    "if_else",
+    "infer_dtype",
+    "is_not_null",
+    "is_null",
+    "isin",
+    "length",
+    "le",
+    "lit",
+    "lt",
+    "log",
+    "mul",
+    "month",
+    "ne",
+    "not_",
+    "or_",
+    "over",
+    "pow_",
+    "replace",
+    "strip",
+    "split",
+    "round_",
+    "starts_with",
+    "sub",
+    "truediv",
+    "upper",
+    "lower",
+    "year",
+    "exp",
+    "clip",
+    "xor",
+    "sqrt",
+    "is_finite",
+]