calc-flow-python 4.0.0__cp313-abi3-win_amd64.whl

calc_flow/config.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+from pydantic import GetJsonSchemaHandler, RootModel, ValidationError, model_validator
+from pydantic_core import CoreSchema, PydanticCustomError
+
+from calc_flow import _native
+
+type JSONValue = (
+    None | bool | int | float | str | list[JSONValue] | dict[str, JSONValue]
+)
+_MAX_JSON_DEPTH = 32
+
+
+def _json_error(message: str) -> ValueError:
+    return ValueError(message)
+
+
+def _parse_issue_path(path: str) -> tuple[str | int, ...]:
+    dotted = path.replace("[", ".").replace("]", "")
+    parts: list[str | int] = []
+    for segment in dotted.split("."):
+        if segment == "":
+            continue
+        parts.append(int(segment) if segment.isdigit() else segment)
+    return tuple(parts)
+
+
+def _native_issues(error: Exception) -> tuple[dict[str, str], ...]:
+    raw = getattr(error, "issues", ())
+    return tuple(
+        issue
+        for issue in raw
+        if isinstance(issue, dict)
+        and isinstance(issue.get("path"), str)
+        and isinstance(issue.get("code"), str)
+        and isinstance(issue.get("message"), str)
+    )
+
+
+def _structured_project_error(issues: tuple[dict[str, str], ...]) -> ValidationError:
+    return ValidationError.from_exception_data(
+        "ProjectDocument",
+        [
+            {
+                "type": PydanticCustomError(issue["code"], issue["message"]),
+                "loc": _parse_issue_path(issue["path"]),
+                "input": None,
+            }
+            for issue in issues
+        ],
+    )
+
+
+def _validate_json_value(value: object) -> None:
+    pending: list[tuple[object, int, frozenset[int]]] = [(value, 0, frozenset())]
+    while pending:
+        current, depth, ancestors = pending.pop()
+        if depth > _MAX_JSON_DEPTH:
+            raise _json_error(
+                f"project exceeds the maximum JSON depth of {_MAX_JSON_DEPTH}"
+            )
+        if current is None or isinstance(current, (bool, str)):
+            continue
+        if isinstance(current, int):
+            if not -(2**63) <= current <= 2**64 - 1:
+                raise _json_error("project integer is outside the portable JSON range")
+            continue
+        if isinstance(current, float):
+            if not math.isfinite(current):
+                raise _json_error("project JSON numbers must be finite")
+            continue
+        if type(current) is dict:
+            identity = id(current)
+            if identity in ancestors:
+                raise _json_error("project contains a cycle")
+            nested_ancestors = ancestors | {identity}
+            for key, child in current.items():
+                if not isinstance(key, str):
+                    raise _json_error("project JSON object keys must be strings")
+                pending.append((child, depth + 1, nested_ancestors))
+            continue
+        if type(current) is list:
+            identity = id(current)
+            if identity in ancestors:
+                raise _json_error("project contains a cycle")
+            nested_ancestors = ancestors | {identity}
+            pending.extend((child, depth + 1, nested_ancestors) for child in current)
+            continue
+        raise _json_error(
+            f"project contains a non-JSON value of type {type(current).__name__}"
+        )
+
+
+def _canonicalize(value: object) -> dict[str, JSONValue]:
+    _validate_json_value(value)
+    try:
+        encoded = json.dumps(
+            value, allow_nan=False, separators=(",", ":"), sort_keys=True
+        )
+        canonical = _native.validate_project_json(encoded)
+    except _native.ConfigError as error:
+        issues = _native_issues(error)
+        if issues:
+            raise _structured_project_error(issues) from error
+        raise _json_error(str(error)) from error
+    except Exception as error:
+        raise _json_error(str(error)) from error
+    parsed = json.loads(canonical)
+    if not isinstance(parsed, dict):
+        raise _json_error("project root must be a JSON object")
+    return parsed
+
+
+def _reject_duplicate_pairs(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            raise _json_error(f"duplicate JSON object key {key!r}")
+        result[key] = value
+    return result
+
+
+def _openapi_project_schema(component_name: str) -> dict[str, Any]:
+    reference_prefix = f"#/components/schemas/{component_name}/$defs/"
+
+    def rewrite_references(value: object) -> object:
+        if type(value) is dict:
+            rewritten = {key: rewrite_references(item) for key, item in value.items()}
+            reference = rewritten.get("$ref")
+            if isinstance(reference, str) and reference.startswith("#/$defs/"):
+                rewritten["$ref"] = reference_prefix + reference.removeprefix(
+                    "#/$defs/"
+                )
+            return rewritten
+        if type(value) is list:
+            return [rewrite_references(item) for item in value]
+        return value
+
+    schema = rewrite_references(json.loads(_native.project_json_schema()))
+    assert isinstance(schema, dict)
+    return schema
+
+
+class ProjectDocument(RootModel[dict[str, JSONValue]]):
+    @model_validator(mode="before")
+    @classmethod
+    def _validate_with_rust(cls, value: object) -> dict[str, JSONValue]:
+        return _canonicalize(value)
+
+    @classmethod
+    def model_validate_json(
+        cls,
+        json_data: str | bytes | bytearray,
+        *,
+        strict: bool | None = None,
+        extra: str | None = None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        by_name: bool | None = None,
+    ) -> ProjectDocument:
+        del extra
+        try:
+            parsed = json.loads(json_data, object_pairs_hook=_reject_duplicate_pairs)
+        except RecursionError as cause:
+            validation_error = _json_error(
+                "project JSON exceeds the maximum nesting depth"
+            )
+            raise ValidationError.from_exception_data(
+                cls.__name__,
+                [
+                    {
+                        "type": "value_error",
+                        "loc": (),
+                        "input": json_data,
+                        "ctx": {"error": validation_error},
+                    }
+                ],
+            ) from cause
+        except (TypeError, ValueError, UnicodeDecodeError) as error:
+            raise ValidationError.from_exception_data(
+                cls.__name__,
+                [
+                    {
+                        "type": "value_error",
+                        "loc": (),
+                        "input": json_data,
+                        "ctx": {"error": ValueError(str(error))},
+                    }
+                ],
+            ) from error
+        return cls.model_validate(
+            parsed,
+            strict=strict,
+            context=context,
+            by_alias=by_alias,
+            by_name=by_name,
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+    ) -> dict[str, Any]:
+        del core_schema, handler
+        return _openapi_project_schema(cls.__name__)
+
+    @classmethod
+    def model_json_schema(cls, *args: object, **kwargs: object) -> dict[str, Any]:
+        del args, kwargs
+        return json.loads(_native.project_json_schema())
+
+    def canonical_json(self) -> str:
+        encoded = json.dumps(
+            self.root, allow_nan=False, separators=(",", ":"), sort_keys=True
+        )
+        return _native.validate_project_json(encoded)

calc_flow/errors.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from calc_flow._native import (
+    CalcFlowError,
+    CancelledError,
+    CheckpointError,
+    CheckpointPublicationUnknownError,
+    CompileError,
+    ConfigError,
+    ExecutionError,
+    ProviderError,
+    StreamingRuntimeError,
+)
+
+__all__ = [
+    "CalcFlowError",
+    "CancelledError",
+    "CheckpointPublicationUnknownError",
+    "CheckpointError",
+    "CompileError",
+    "ConfigError",
+    "ExecutionError",
+    "ProviderError",
+    "StreamingRuntimeError",
+]

calc_flow/join_spec.py

@@ -0,0 +1,156 @@
+"""The stream-join wire specification shared by every surface.
+
+``calc_flow.pipeline`` (project JSON), ``calc_flow.symbolic`` (node
+attrs), and the lowering path each encode the same bounded inner join
+contract. The value containers, validators, and the single wire-spec
+builder live here so the contract is defined once and the symbolic layer
+no longer imports runtime-side helpers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import timedelta
+
+STREAM_JOIN_MAX_SAFE_JSON_INTEGER = 9_007_199_254_740_991
+
+
+@dataclass(frozen=True, slots=True)
+class JoinTimeBounds:
+    """Inclusive non-negative event-time distances around a left row."""
+
+    before: timedelta
+    after: timedelta
+
+    def __post_init__(self) -> None:
+        timedelta_micros(self.before, "before")
+        timedelta_micros(self.after, "after")
+
+
+@dataclass(frozen=True, slots=True)
+class JoinStateLimits:
+    """Required logical state and per-input match limits."""
+
+    max_state_rows_per_side: int
+    max_state_bytes_per_side: int
+    max_matches_per_input_batch: int
+
+    def __post_init__(self) -> None:
+        for field_name in (
+            "max_state_rows_per_side",
+            "max_state_bytes_per_side",
+            "max_matches_per_input_batch",
+        ):
+            value = getattr(self, field_name)
+            if value.__class__ is not int:
+                raise TypeError(f"{field_name} must be an exact int")
+            if not 1 <= value <= STREAM_JOIN_MAX_SAFE_JSON_INTEGER:
+                raise ValueError(
+                    f"{field_name} must be in 1..={STREAM_JOIN_MAX_SAFE_JSON_INTEGER}"
+                )
+
+
+@dataclass(frozen=True, slots=True)
+class JoinSideWire:
+    """One join side's wire-level keys, event time, and output prefix."""
+
+    keys: tuple[str, ...]
+    event_time: str
+    prefix: str
+
+
+def require_equal_key_counts(
+    left_keys: Sequence[str], right_keys: Sequence[str]
+) -> None:
+    if len(left_keys) != len(right_keys):
+        raise ValueError("left_keys and right_keys must have equal length")
+
+
+def require_event_time_columns(left_event_time: str, right_event_time: str) -> None:
+    for field_name, value in (
+        ("left_event_time", left_event_time),
+        ("right_event_time", right_event_time),
+    ):
+        if not isinstance(value, str) or not value:
+            raise TypeError(f"{field_name} must be a non-empty string")
+
+
+def require_join_bounds(bounds: JoinTimeBounds) -> None:
+    if not isinstance(bounds, JoinTimeBounds):
+        raise TypeError("bounds must be a calc_flow.JoinTimeBounds")
+
+
+def require_join_limits(limits: JoinStateLimits) -> None:
+    if not isinstance(limits, JoinStateLimits):
+        raise TypeError("limits must be a calc_flow.JoinStateLimits")
+
+
+def _portable_identifier(value: object) -> bool:
+    return isinstance(value, str) and value.isidentifier() and value.isascii()
+
+
+def require_distinct_prefixes(left_prefix: str, right_prefix: str) -> None:
+    if not _portable_identifier(left_prefix) or not _portable_identifier(right_prefix):
+        raise ValueError("prefixes must be distinct portable identifiers")
+    if left_prefix == right_prefix:
+        raise ValueError("prefixes must be distinct portable identifiers")
+
+
+def timedelta_micros(value: timedelta, field_name: str) -> int:
+    # Exact-type checks: bool is an int subclass and timedelta subclasses
+    # must not satisfy the wire contract, so compare classes directly.
+    if value.__class__ is not timedelta:
+        raise TypeError(f"{field_name} must be an exact datetime.timedelta")
+    micros = (
+        value.days * 86_400_000_000 + value.seconds * 1_000_000 + value.microseconds
+    )
+    if not 0 <= micros <= STREAM_JOIN_MAX_SAFE_JSON_INTEGER:
+        raise ValueError(
+            f"{field_name} must resolve to "
+            f"0..={STREAM_JOIN_MAX_SAFE_JSON_INTEGER} microseconds"
+        )
+    return micros
+
+
+def bounds_wire(before_micros: int, after_micros: int) -> dict[str, int]:
+    """Build the wire ``bounds`` object from resolved microsecond distances."""
+
+    return {"before_micros": before_micros, "after_micros": after_micros}
+
+
+def limits_wire(
+    max_state_rows_per_side: int,
+    max_state_bytes_per_side: int,
+    max_matches_per_input_batch: int,
+) -> dict[str, int]:
+    """Build the wire ``limits`` object from the three resolved limits."""
+
+    return {
+        "max_state_rows_per_side": max_state_rows_per_side,
+        "max_state_bytes_per_side": max_state_bytes_per_side,
+        "max_matches_per_input_batch": max_matches_per_input_batch,
+    }
+
+
+def join_wire_spec(
+    left: JoinSideWire,
+    right: JoinSideWire,
+    bounds: Mapping[str, int],
+    limits: Mapping[str, int],
+    *,
+    join_type: str = "inner",
+) -> dict[str, object]:
+    """Build the canonical ``stream_join`` operator wire specification."""
+
+    return {
+        "join_type": join_type,
+        "left_keys": list(left.keys),
+        "right_keys": list(right.keys),
+        "left_event_time": left.event_time,
+        "right_event_time": right.event_time,
+        "bounds": dict(bounds),
+        "limits": dict(limits),
+        "left_prefix": left.prefix,
+        "right_prefix": right.prefix,
+    }