pydantable-protocol 1.14.0__tar.gz

pydantable_protocol-1.14.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: pydantable-protocol
+Version: 1.14.0
+Summary: Execution engine protocols for pydantable (zero runtime dependencies).
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pydantable-protocol
+
+Zero-dependency execution engine protocols for **pydantable**. See the [repository root README](../README.md) for the full project.

pydantable_protocol-1.14.0/README.md

@@ -0,0 +1,3 @@
+# pydantable-protocol
+
+Zero-dependency execution engine protocols for **pydantable**. See the [repository root README](../README.md) for the full project.

pydantable_protocol-1.14.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pydantable-protocol"
+version = "1.14.0"
+description = "Execution engine protocols for pydantable (zero runtime dependencies)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[tool.setuptools]
+package-dir = {"" = "python"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["python"]

pydantable_protocol-1.14.0/python/pydantable_protocol/__init__.py

@@ -0,0 +1,28 @@
+"""Zero-dependency protocols for pydantable-compatible execution engines."""
+
+from __future__ import annotations
+
+from pydantable_protocol.exceptions import (
+    MissingRustExtensionError,
+    UnsupportedEngineOperationError,
+)
+from pydantable_protocol.protocols import (
+    EngineCapabilities,
+    ExecutionEngine,
+    PlanExecutor,
+    SinkWriter,
+    stub_engine_capabilities,
+)
+
+__version__ = "1.14.0"
+
+__all__ = [
+    "EngineCapabilities",
+    "ExecutionEngine",
+    "MissingRustExtensionError",
+    "PlanExecutor",
+    "SinkWriter",
+    "UnsupportedEngineOperationError",
+    "__version__",
+    "stub_engine_capabilities",
+]

pydantable_protocol-1.14.0/python/pydantable_protocol/exceptions.py

@@ -0,0 +1,29 @@
+"""Errors shared across pydantable distributions (no pydantable dependency)."""
+
+from __future__ import annotations
+
+_MISSING_CORE = (
+    "The pydantable native extension (pydantable-native) is required for this "
+    "operation. Build from source with: maturin develop --manifest-path "
+    "pydantable-core/Cargo.toml — or install a published wheel "
+    "(pip install pydantable-native or pydantable-meta). See docs/DEVELOPER.md."
+)
+
+
+class MissingRustExtensionError(NotImplementedError):
+    """Raised when the compiled native extension is missing or too old for the API.
+
+    Subclasses :exc:`NotImplementedError` so broad handlers keep matching.
+    Install **pydantable-native** (or **pydantable-meta**) or build from source.
+    """
+
+    def __init__(self, detail: str | None = None) -> None:
+        super().__init__(detail if detail is not None else _MISSING_CORE)
+
+
+class UnsupportedEngineOperationError(ValueError):
+    """Raised when an execution engine cannot perform a requested operation.
+
+    Third-party backends should raise this (or a subclass) so callers can catch
+    engine limits without importing ``pydantable``.
+    """

pydantable_protocol-1.14.0/python/pydantable_protocol/protocols.py

@@ -0,0 +1,390 @@
+"""Structural protocols and capability flags for pydantable execution engines.
+
+These definitions are published in a **zero-dependency** distribution so
+third-party backends (for example a SQL engine package) can implement
+:class:`ExecutionEngine` and type-check against it **without** installing
+``pydantable``.
+
+Unsupported calls should raise
+:class:`~pydantable_protocol.exceptions.UnsupportedEngineOperationError`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+
+@dataclass(frozen=True, slots=True)
+class EngineCapabilities:
+    """Feature flags for an execution engine (native, stub, or future backends)."""
+
+    backend: Literal["native", "stub", "custom"]
+    extension_loaded: bool
+    has_execute_plan: bool
+    has_async_execute_plan: bool
+    has_async_collect_plan_batches: bool
+    has_sink_parquet: bool
+    has_sink_csv: bool
+    has_sink_ipc: bool
+    has_sink_ndjson: bool
+    has_collect_plan_batches: bool
+    has_execute_join: bool
+    has_execute_groupby_agg: bool
+
+
+def stub_engine_capabilities() -> EngineCapabilities:
+    """Capabilities for minimal stub / test-double execution engines."""
+
+    return EngineCapabilities(
+        backend="stub",
+        extension_loaded=False,
+        has_execute_plan=False,
+        has_async_execute_plan=False,
+        has_async_collect_plan_batches=False,
+        has_sink_parquet=False,
+        has_sink_csv=False,
+        has_sink_ipc=False,
+        has_sink_ndjson=False,
+        has_collect_plan_batches=False,
+        has_execute_join=False,
+        has_execute_groupby_agg=False,
+    )
+
+
+@runtime_checkable
+class PlanExecutor(Protocol):
+    """Execute a logical plan against root data."""
+
+    def execute_plan(
+        self,
+        plan: Any,
+        data: Any,
+        *,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+        error_context: str | None = None,
+    ) -> Any: ...
+
+    async def async_execute_plan(
+        self,
+        plan: Any,
+        data: Any,
+        *,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+        error_context: str | None = None,
+    ) -> Any: ...
+
+    async def async_collect_plan_batches(
+        self,
+        plan: Any,
+        root_data: Any,
+        *,
+        batch_size: int = 65_536,
+        streaming: bool = False,
+    ) -> list[Any]: ...
+
+    def collect_batches(
+        self,
+        plan: Any,
+        root_data: Any,
+        *,
+        batch_size: int = 65_536,
+        streaming: bool = False,
+    ) -> list[Any]: ...
+
+    def execute_join(
+        self,
+        left_plan: Any,
+        left_root_data: Any,
+        right_plan: Any,
+        right_root_data: Any,
+        left_on: Sequence[str],
+        right_on: Sequence[str],
+        how: str,
+        suffix: str,
+        *,
+        validate: str | None = None,
+        coalesce: bool | None = None,
+        join_nulls: bool | None = None,
+        maintain_order: str | None = None,
+        allow_parallel: bool | None = None,
+        force_parallel: bool | None = None,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_groupby_agg(
+        self,
+        plan: Any,
+        root_data: Any,
+        by: Sequence[str],
+        aggregations: Any,
+        *,
+        maintain_order: bool = False,
+        drop_nulls: bool = True,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_concat(
+        self,
+        left_plan: Any,
+        left_root_data: Any,
+        right_plan: Any,
+        right_root_data: Any,
+        how: str,
+        *,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_except_all(
+        self,
+        left_plan: Any,
+        left_root_data: Any,
+        right_plan: Any,
+        right_root_data: Any,
+        *,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_intersect_all(
+        self,
+        left_plan: Any,
+        left_root_data: Any,
+        right_plan: Any,
+        right_root_data: Any,
+        *,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_melt(
+        self,
+        plan: Any,
+        root_data: Any,
+        id_vars: Sequence[str],
+        value_vars: Sequence[str] | None,
+        variable_name: str,
+        value_name: str,
+        *,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_pivot(
+        self,
+        plan: Any,
+        root_data: Any,
+        index: Sequence[str],
+        columns: str,
+        values: Sequence[str],
+        aggregate_function: str,
+        *,
+        pivot_values: Sequence[Any] | None = None,
+        sort_columns: bool = False,
+        separator: str = "_",
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_explode(
+        self,
+        plan: Any,
+        root_data: Any,
+        columns: Sequence[str],
+        *,
+        streaming: bool = False,
+        outer: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_posexplode(
+        self,
+        plan: Any,
+        root_data: Any,
+        list_column: str,
+        pos_name: str,
+        value_name: str,
+        *,
+        streaming: bool = False,
+        outer: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_unnest(
+        self,
+        plan: Any,
+        root_data: Any,
+        columns: Sequence[str],
+        *,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_rolling_agg(
+        self,
+        plan: Any,
+        root_data: Any,
+        on: str,
+        column: str,
+        window_size: int | str,
+        op: str,
+        out_name: str,
+        by: Sequence[str] | None,
+        min_periods: int,
+    ) -> tuple[Any, Any]: ...
+
+    def execute_groupby_dynamic_agg(
+        self,
+        plan: Any,
+        root_data: Any,
+        index_column: str,
+        every: str,
+        period: str | None,
+        by: Sequence[str] | None,
+        aggregations: Any,
+        *,
+        as_python_lists: bool = False,
+        streaming: bool = False,
+    ) -> tuple[Any, Any]: ...
+
+
+@runtime_checkable
+class SinkWriter(Protocol):
+    """Write lazy plan + root to on-disk formats."""
+
+    def write_parquet(
+        self,
+        plan: Any,
+        root_data: Any,
+        path: str,
+        *,
+        streaming: bool = False,
+        write_kwargs: dict[str, Any] | None = None,
+        partition_by: list[str] | tuple[str, ...] | None = None,
+        mkdir: bool = True,
+    ) -> None: ...
+
+    def write_csv(
+        self,
+        plan: Any,
+        root_data: Any,
+        path: str,
+        *,
+        streaming: bool = False,
+        separator: int = ord(","),
+        write_kwargs: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    def write_ipc(
+        self,
+        plan: Any,
+        root_data: Any,
+        path: str,
+        *,
+        streaming: bool = False,
+        compression: str | None = None,
+        write_kwargs: dict[str, Any] | None = None,
+    ) -> None: ...
+
+    def write_ndjson(
+        self,
+        plan: Any,
+        root_data: Any,
+        path: str,
+        *,
+        streaming: bool = False,
+        write_kwargs: dict[str, Any] | None = None,
+    ) -> None: ...
+
+
+@runtime_checkable
+class ExecutionEngine(PlanExecutor, SinkWriter, Protocol):
+    """Full drop-in engine: logical plan transforms, execution, sinks, capabilities."""
+
+    @property
+    def capabilities(self) -> EngineCapabilities: ...
+
+    def make_plan(self, field_types: Any) -> Any: ...
+
+    def has_async_execute_plan(self) -> bool: ...
+
+    def has_async_collect_plan_batches(self) -> bool: ...
+
+    def make_literal(self, *, value: Any) -> Any: ...
+
+    def plan_with_columns(self, plan: Any, columns: dict[str, Any]) -> Any: ...
+
+    def expr_is_global_agg(self, expr: Any) -> bool: ...
+
+    def expr_global_default_alias(self, expr: Any) -> Any: ...
+
+    def plan_global_select(self, plan: Any, items: list[tuple[str, Any]]) -> Any: ...
+
+    def plan_select(self, plan: Any, projects: list[str]) -> Any: ...
+
+    def plan_filter(self, plan: Any, condition_expr: Any) -> Any: ...
+
+    def plan_sort(
+        self,
+        plan: Any,
+        keys: list[str],
+        desc: list[bool],
+        nulls_last: list[bool],
+        maintain_order: bool,
+    ) -> Any: ...
+
+    def plan_unique(
+        self,
+        plan: Any,
+        subset: list[str] | None,
+        keep: str,
+        maintain_order: bool,
+    ) -> Any: ...
+
+    def plan_duplicate_mask(
+        self, plan: Any, subset: list[str] | None, keep: str
+    ) -> Any: ...
+
+    def plan_drop_duplicate_groups(
+        self, plan: Any, subset: list[str] | None
+    ) -> Any: ...
+
+    def plan_drop(self, plan: Any, columns: list[str]) -> Any: ...
+
+    def plan_rename(self, plan: Any, rename_map: Mapping[str, str]) -> Any: ...
+
+    def plan_slice(self, plan: Any, offset: int, length: int) -> Any: ...
+
+    def plan_with_row_count(self, plan: Any, name: str, offset: int) -> Any: ...
+
+    def plan_fill_null(
+        self,
+        plan: Any,
+        subset: list[str] | None,
+        value: Any,
+        strategy: str | None,
+    ) -> Any: ...
+
+    def plan_drop_nulls(
+        self,
+        plan: Any,
+        subset: list[str] | None,
+        how: str,
+        threshold: int | None,
+    ) -> Any: ...
+
+    def plan_rolling_agg(
+        self,
+        plan: Any,
+        column: str,
+        window_size: int,
+        min_periods: int,
+        op: str,
+        out_name: str,
+        partition_by: Sequence[str] | None = None,
+    ) -> Any: ...

pydantable_protocol-1.14.0/python/pydantable_protocol.egg-info/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: pydantable-protocol
+Version: 1.14.0
+Summary: Execution engine protocols for pydantable (zero runtime dependencies).
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pydantable-protocol
+
+Zero-dependency execution engine protocols for **pydantable**. See the [repository root README](../README.md) for the full project.

pydantable_protocol-1.14.0/python/pydantable_protocol.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+python/pydantable_protocol/__init__.py
+python/pydantable_protocol/exceptions.py
+python/pydantable_protocol/protocols.py
+python/pydantable_protocol/py.typed
+python/pydantable_protocol.egg-info/PKG-INFO
+python/pydantable_protocol.egg-info/SOURCES.txt
+python/pydantable_protocol.egg-info/dependency_links.txt
+python/pydantable_protocol.egg-info/top_level.txt

pydantable_protocol-1.14.0/python/pydantable_protocol.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pydantable_protocol-1.14.0/python/pydantable_protocol.egg-info/top_level.txt

@@ -0,0 +1 @@
+pydantable_protocol

pydantable_protocol-1.14.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+