equiframe 0.12.4__py3-none-any.whl

equiframe/local.py

@@ -0,0 +1,126 @@
+"""Local-only artifact storage; verified, exclusive copies without overwrites."""
+
+import hashlib
+import os
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+from urllib.request import url2pathname
+from uuid import uuid4
+
+from equiframe._base import Text
+from equiframe._regular_io import (
+    local_input_path,
+    new_directory_path,
+    open_regular_file,
+    regular_directory,
+)
+from equiframe.errors import ArtifactIntegrityError, ArtifactIOError, CapabilityError
+from equiframe.types import ArtifactRef
+
+_FORMATS = {".json": "json", ".jsonl": "jsonl", ".arrow": "arrow", ".parquet": "parquet"}
+_BUNDLE_PATHS: ContextVar[Mapping[str, Path] | None] = ContextVar("bundle_paths", default=None)
+
+
+@contextmanager
+def _bundle_paths(paths: Mapping[str, Path]) -> Iterator[None]:
+    """Resolve only verified bundle members, restoring scope even after a failure."""
+    token = _BUNDLE_PATHS.set(dict(paths))
+    try:
+        yield
+    finally:
+        _BUNDLE_PATHS.reset(token)
+
+
+def local_path(ref: ArtifactRef) -> Path:
+    mapping = _BUNDLE_PATHS.get()
+    if mapping is not None:
+        if ref.uri not in mapping:
+            raise ArtifactIntegrityError("artifact reference is outside the portable inventory")
+        return mapping[ref.uri]
+    parts = urlsplit(ref.uri)
+    if parts.scheme != "file" or parts.netloc not in ("", "localhost"):
+        raise CapabilityError("only local file URIs are supported; remote access is unavailable")
+    decoded = unquote(parts.path)
+    if decoded.startswith("//") or "\\" in decoded:
+        raise CapabilityError("network/UNC paths are not supported")
+    return Path(url2pathname(parts.path))
+
+
+def _copy(source: Path, destination: Path, expected: ArtifactRef | None = None) -> tuple[str, int]:
+    source = local_input_path(source)
+    destination = local_input_path(destination)
+    new_directory_path(destination.parent)
+    temporary = destination.with_name(destination.name + "." + uuid4().hex + ".part")
+    digest = hashlib.sha256()
+    size = 0
+    try:
+        with open_regular_file(source) as reader:
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            regular_directory(destination.parent)
+            with temporary.open("xb") as writer:
+                while True:
+                    capacity = 1024 * 1024
+                    if expected is not None:
+                        capacity = min(capacity, expected.size_bytes - size + 1)
+                    block = reader.read(capacity)
+                    if not block:
+                        break
+                    if expected is not None and size + len(block) > expected.size_bytes:
+                        raise ArtifactIntegrityError("artifact exceeds its declared byte size")
+                    writer.write(block)
+                    digest.update(block)
+                    size += len(block)
+                writer.flush()
+                os.fsync(writer.fileno())
+        if expected is not None and (
+            digest.hexdigest() != expected.sha256 or size != expected.size_bytes
+        ):
+            raise ArtifactIntegrityError("artifact bytes do not match declared SHA-256/size")
+        # Atomic publication that fails if destination exists, including concurrent writers.
+        os.link(temporary, destination)
+        return digest.hexdigest(), size
+    except (OSError, ValueError) as error:
+        raise ArtifactIOError(
+            "cannot copy/publish local artifact: " + type(error).__name__
+        ) from error
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+class LocalArtifactStore:
+    def __init__(self, root: Path) -> None:
+        if not isinstance(root, Path):
+            raise TypeError("artifact store root must be a Path")
+        self.root = new_directory_path(local_input_path(root))
+
+    def put(self, path: Path, *, media_type: str) -> ArtifactRef:
+        from pydantic import TypeAdapter
+
+        if not isinstance(path, Path):
+            raise TypeError("artifact input must be a Path")
+        media_type = TypeAdapter(Text).validate_python(media_type, strict=True)
+        format_name = _FORMATS.get(path.suffix.lower())
+        if format_name is None:
+            raise CapabilityError("supported artifact suffixes: .json, .jsonl, .arrow, .parquet")
+        destination = self.root / (uuid4().hex + path.suffix.lower())
+        sha256, size = _copy(path, destination)
+        return ArtifactRef.model_validate(
+            {
+                "schema_version": "1.0",
+                "uri": destination.as_uri(),
+                "sha256": sha256,
+                "format": format_name,
+                "media_type": media_type,
+                "size_bytes": size,
+            }
+        )
+
+    def get(self, ref: ArtifactRef, destination: Path) -> Path:
+        if not isinstance(destination, Path):
+            raise TypeError("artifact destination must be a Path")
+        ref = ArtifactRef.model_validate(ref)
+        _copy(local_path(ref), destination, ref)
+        return destination

equiframe/migration/__init__.py

@@ -0,0 +1,94 @@
+"""Extensible declarative ETL migration; native engines remain optional imports."""
+
+from .io import migration_summary, read_migration, render_migration_report
+from .ports import CompiledPlan, CompilerRegistry, PlanCompiler, native_compiler_registry
+from .runner import ExpectedInput, check_migration, migrate
+from .runner_types import (
+    CompilerRecord,
+    MigrationOptions,
+    MigrationRequest,
+    MigrationResult,
+    MigrationSpec,
+    MigrationStage,
+)
+from .types import (
+    Aggregate,
+    Boolean,
+    Cast,
+    CastColumn,
+    Column,
+    Compare,
+    CompilationCheck,
+    CompilationDiagnostic,
+    DecimalRound,
+    EquiJoin,
+    Filter,
+    IRColumn,
+    IsNaN,
+    IsNull,
+    JoinKey,
+    LiteralExpression,
+    LocalizeTimestamp,
+    Measure,
+    NamedExpression,
+    NodeSchema,
+    Not,
+    Project,
+    RelationalPlan,
+    Scan,
+    Sort,
+    SortKey,
+    Window,
+    WindowMeasure,
+)
+from .validation import ValidatedIR, ir_fingerprint, validate_ir
+
+__all__ = [
+    "Aggregate",
+    "Boolean",
+    "Cast",
+    "CastColumn",
+    "Column",
+    "Compare",
+    "CompilationCheck",
+    "CompilationDiagnostic",
+    "CompiledPlan",
+    "CompilerRecord",
+    "CompilerRegistry",
+    "DecimalRound",
+    "EquiJoin",
+    "ExpectedInput",
+    "Filter",
+    "IRColumn",
+    "IsNaN",
+    "IsNull",
+    "JoinKey",
+    "LiteralExpression",
+    "LocalizeTimestamp",
+    "Measure",
+    "MigrationOptions",
+    "MigrationRequest",
+    "MigrationResult",
+    "MigrationSpec",
+    "MigrationStage",
+    "NamedExpression",
+    "NodeSchema",
+    "Not",
+    "PlanCompiler",
+    "Project",
+    "RelationalPlan",
+    "Scan",
+    "Sort",
+    "SortKey",
+    "ValidatedIR",
+    "Window",
+    "WindowMeasure",
+    "check_migration",
+    "ir_fingerprint",
+    "migrate",
+    "migration_summary",
+    "native_compiler_registry",
+    "read_migration",
+    "render_migration_report",
+    "validate_ir",
+]

equiframe/migration/_physical.py

@@ -0,0 +1,8 @@
+"""Compatibility aliases for the shared captured-table implementation.
+
+Physical table verification belongs to captured evidence, not migration. The
+aliases retain internal consumer identity while formats and behavior stay intact.
+"""
+
+from equiframe._physical import physical_size as physical_size
+from equiframe._physical import verify_table_metadata as verify_table_metadata

equiframe/migration/backends/_timestamp_transport.py

@@ -0,0 +1,109 @@
+"""Explicit timestamp tick encoding for trusted IR implementations.
+
+This codec changes representation only. It never localizes a wall time, chooses
+an offset, changes a tick, or converts a wrongly typed native result to fit a
+contract. Each compiler remains responsible for its native computation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from equiframe.contracts import Contract, TimestampType
+from equiframe.errors import CapabilityError
+from equiframe.registry import DuckDBTransformation, PolarsTransformation
+from equiframe.tables import LoadedTable, check_arrow
+
+if TYPE_CHECKING:
+    import pyarrow as pa
+
+_TimestampColumns = tuple[tuple[str, TimestampType], ...]
+
+
+def _view_columns(table: pa.Table, columns: _TimestampColumns, *, encode: bool) -> pa.Table:
+    """Reinterpret exact 64-bit buffers, retaining values, masks and metadata."""
+    import pyarrow as pa
+
+    check_arrow(table)
+    result: pa.Table = table
+    for name, logical in columns:
+        position = result.schema.get_field_index(name)
+        if position < 0:
+            raise CapabilityError("IR timestamp transport column is missing")
+        field = result.schema.field(position)
+        timestamp = pa.timestamp(logical.unit, tz=logical.timezone)
+        required, target = (timestamp, pa.int64()) if encode else (pa.int64(), timestamp)
+        if field.type != required:
+            raise CapabilityError("IR timestamp transport received an unexpected physical type")
+        array: pa.ChunkedArray = pa.chunked_array(
+            [chunk.view(target) for chunk in result.column(position).chunks], type=target
+        )
+        result = result.set_column(
+            position,
+            pa.field(name, target, nullable=field.nullable, metadata=field.metadata),
+            array,
+        )
+    check_arrow(result)
+    return result
+
+
+@dataclass(frozen=True)
+class _TimestampCodec:
+    inputs: tuple[tuple[str, _TimestampColumns], ...] = ()
+    output: _TimestampColumns = ()
+
+    @classmethod
+    def for_contract(cls, contract: Contract) -> _TimestampCodec:
+        """Describe the encoding only after the compiler validates its IR schema."""
+        return cls(
+            inputs=tuple(
+                (
+                    table.name,
+                    tuple(
+                        (column.name, column.logical_type)
+                        for column in table.schema_spec.columns
+                        if isinstance(column.logical_type, TimestampType)
+                    ),
+                )
+                for table in contract.inputs
+                if any(isinstance(c.logical_type, TimestampType) for c in table.schema_spec.columns)
+            ),
+            output=tuple(
+                (column.name, column.logical_type)
+                for column in contract.output.schema_spec.columns
+                if isinstance(column.logical_type, TimestampType)
+            ),
+        )
+
+    def encode_input(self, name: str, loaded: LoadedTable) -> LoadedTable:
+        columns = dict(self.inputs).get(name, ())
+        if not columns:
+            return loaded
+        return replace(
+            loaded,
+            table=_view_columns(loaded.table, columns, encode=True),
+            native=None,
+            native_types=(),
+            notes=(*loaded.notes, "IR internal timestamp encoding: unchanged signed int64 ticks."),
+        )
+
+    def encode_inputs(self, inputs: Mapping[str, LoadedTable]) -> dict[str, LoadedTable]:
+        descriptors = dict(self.inputs)
+        if not descriptors.keys() <= inputs.keys():
+            raise CapabilityError("IR timestamp transport input is missing")
+        return {name: self.encode_input(name, loaded) for name, loaded in inputs.items()}
+
+    def decode_output(self, table: pa.Table) -> pa.Table:
+        return _view_columns(table, self.output, encode=False)
+
+
+@dataclass(frozen=True)
+class _TimestampDuckDBTransformation(DuckDBTransformation):
+    timestamp_codec: _TimestampCodec | None = None
+
+
+@dataclass(frozen=True)
+class _TimestampPolarsTransformation(PolarsTransformation):
+    timestamp_codec: _TimestampCodec | None = None