equiframe 0.12.4__py3-none-any.whl

equiframe/__main__.py

@@ -0,0 +1,3 @@
+from equiframe.cli import main
+
+main()

equiframe/_base.py

@@ -0,0 +1,84 @@
+"""Shared strict configuration and validation helpers (not public API)."""
+
+from typing import Annotated, ClassVar
+
+from pydantic import (
+    AfterValidator,
+    BaseModel,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    ValidationError,
+)
+from pydantic_core import PydanticCustomError
+from typing_extensions import Never
+
+
+class _ExplicitOutcome:
+    """Field-free guard for the explicitly selected operational outcome models.
+
+    Object presence, technical completion and an approval decision are separate.
+    This mixin intentionally does not apply to every frozen model.
+    """
+
+    __slots__ = ()
+    _truth_value_guidance: ClassVar[str]
+
+    def __bool__(self) -> Never:
+        raise TypeError(f"{type(self).__name__} has no truth value; {self._truth_value_guidance}")
+
+
+class FrozenModel(BaseModel):
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        validate_default=True,
+        revalidate_instances="always",
+        allow_inf_nan=False,
+        hide_input_in_errors=True,
+    )
+
+
+def _text(value: str) -> str:
+    if not value.strip() or value != value.strip():
+        raise ValueError("text must be nonempty and have no surrounding whitespace")
+    if any(0xD800 <= ord(char) <= 0xDFFF for char in value):
+        raise ValueError("text must contain valid Unicode scalar values")
+    return value
+
+
+Text = Annotated[str, StringConstraints(min_length=1), AfterValidator(_text)]
+Identifier = Annotated[Text, StringConstraints(pattern=r"^[A-Za-z][A-Za-z0-9_.-]*$")]
+PositiveInt = Annotated[int, Field(gt=0)]
+NonNegativeInt = Annotated[int, Field(ge=0)]
+
+
+def fail(code: str, message: str, *location: str | int) -> Never:
+    """Attach a cross-field failure to its actual field, including nested paths."""
+    raise ValidationError.from_exception_data(
+        "EquiFrame",
+        [{"type": PydanticCustomError(code, message), "loc": location, "input": None}],
+    )
+
+
+def unique(values: tuple[str, ...], field: str) -> None:
+    seen: set[str] = set()
+    for index, value in enumerate(values):
+        if value in seen:
+            fail("duplicate_reference", "repeated reference: " + value, field, index)
+        seen.add(value)
+
+
+def strict_int_literal(value: object) -> int:
+    """Preserve strict integer metadata before Literal's numeric equality lookup."""
+    if type(value) is not int:
+        raise PydanticCustomError("literal_type", "integer literals require an exact integer type")
+    return value
+
+
+def strict_bool_literal(value: object) -> bool:
+    """Do not normalize numeric 0/1 to a declared boolean literal."""
+    if type(value) is not bool:
+        raise PydanticCustomError("literal_type", "boolean literals require an exact boolean type")
+    return value

equiframe/_cli_support.py

@@ -0,0 +1,125 @@
+"""Fixed-text CLI guidance, separate from semantic decisions and exit-code policy.
+
+The caller owns its historical code and status. This helper never formats an
+exception, cause, model error, path or user-supplied value into terminal output.
+"""
+
+import json
+
+import typer
+from pydantic import ValidationError
+from typing_extensions import Never
+
+from equiframe.errors import (
+    ArtifactIntegrityError,
+    ArtifactIOError,
+    CapabilityError,
+    ContractIOError,
+    ContractValidationError,
+    ExecutionCancelled,
+    ExecutionTimeout,
+    InvalidExecutionInput,
+    MissingDependencyError,
+    NativeEngineError,
+    ResourceLimitError,
+)
+
+
+def failure_hint(error: Exception, *, input_validation: bool = True) -> tuple[str, str]:
+    """Return a bounded category and actionable guidance without inspecting payloads."""
+    if isinstance(error, (ArtifactIOError, ContractIOError)) and isinstance(
+        error.__cause__,
+        (
+            FileNotFoundError,
+            FileExistsError,
+            PermissionError,
+            IsADirectoryError,
+            NotADirectoryError,
+        ),
+    ):
+        # Inspect only the immediate OS error class, never its path or message.
+        return failure_hint(error.__cause__, input_validation=input_validation)
+    if isinstance(error, FileNotFoundError):
+        return "missing_path", "Check that the requested input and its parent directory exist."
+    if isinstance(error, FileExistsError):
+        return "existing_output", "Choose a new output path; existing evidence is not overwritten."
+    if isinstance(error, PermissionError):
+        return "permission_denied", "Check read access to inputs and write access to the output."
+    if isinstance(error, (IsADirectoryError, NotADirectoryError)):
+        return "path_kind", "Check which arguments require files and which require directories."
+    if isinstance(error, MissingDependencyError):
+        return "optional_dependency", "Check the required extra in this interpreter's environment."
+    if isinstance(error, ImportError):
+        return "module_unavailable", "Check the selected module and its installed dependencies."
+    if isinstance(error, ArtifactIntegrityError):
+        return "evidence_integrity", "Restore the original evidence or rerun into a new directory."
+    if isinstance(error, CapabilityError):
+        return "unsupported_capability", "Check the documented engine and representation limits."
+    if isinstance(error, ExecutionCancelled):
+        return "cancelled", "Keep partial evidence; retry only when the operation is still needed."
+    if isinstance(error, ExecutionTimeout):
+        return "timeout", "Review the workload and explicit time budget before retrying."
+    if isinstance(error, ResourceLimitError):
+        return (
+            "resource_limit",
+            "Review the workload and explicit resource budgets before retrying.",
+        )
+    if isinstance(error, NativeEngineError):
+        return "native_engine", "Inspect the recorded stage and the trusted native transformation."
+    if isinstance(error, (OSError, ArtifactIOError, ContractIOError)):
+        return "io_failure", "Check input availability, output access and available disk space."
+    if isinstance(error, (json.JSONDecodeError, UnicodeDecodeError)):
+        return "document_syntax", "Use a valid UTF-8 JSON document for the selected command."
+    if isinstance(error, (ValidationError, ContractValidationError)):
+        if isinstance(error, ContractValidationError) and any(
+            issue.code == "duplicate_json_key" for issue in error.issues
+        ):
+            return (
+                "duplicate_json_key",
+                "Use one value per JSON member; duplicate keys are refused.",
+            )
+        return (
+            (
+                "document_validation",
+                "Check the request's required fields, types and schema version.",
+            )
+            if input_validation
+            else (
+                "evidence_validation",
+                "Check the evidence format and restore its original files.",
+            )
+        )
+    if isinstance(error, (ValueError, InvalidExecutionInput)):
+        return (
+            ("input_configuration", "Check the command arguments and declared input constraints.")
+            if input_validation
+            else (
+                "evidence_validation",
+                "Check the evidence format and restore its original files.",
+            )
+        )
+    return "operation_failure", "Inspect any retained evidence and prepare a minimal reproduction."
+
+
+def write_failure(
+    error: Exception,
+    *,
+    code: str,
+    input_validation: bool = True,
+) -> None:
+    """Retain the original first-line code and add one fixed, human-readable hint."""
+    category, hint = failure_hint(error, input_validation=input_validation)
+    typer.echo(code, err=True)
+    typer.echo(f"hint[{category}]: {hint}", err=True)
+
+
+def exit_with_failure(
+    error: Exception,
+    *,
+    code: str,
+    exit_code: int,
+    input_validation: bool = True,
+) -> Never:
+    """Write guidance and preserve the caller's existing Typer exit-code policy."""
+    write_failure(error, code=code, input_validation=input_validation)
+    raise typer.Exit(code=exit_code) from None

equiframe/_comparison_io.py

@@ -0,0 +1,161 @@
+"""Streaming local snapshots/readers. No read_all/read_table on comparison paths."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from equiframe.errors import ArtifactIntegrityError, CapabilityError, ResourceLimitError
+from equiframe.local import local_path
+from equiframe.tables import ArrowInput, require_dependency
+from equiframe.types import ArtifactRef
+
+if TYPE_CHECKING:
+    import pyarrow as pa
+
+    from equiframe.comparison_types import ComparisonOptions
+
+
+def file_ref(
+    path: Path, format_name: str, *, check: Callable[[], None] | None = None
+) -> ArtifactRef:
+    digest = hashlib.sha256()
+    size = 0
+    with path.open("rb") as source:
+        while block := source.read(1024 * 1024):
+            if check:
+                check()
+            digest.update(block)
+            size += len(block)
+    return ArtifactRef.model_validate(
+        dict(
+            schema_version="1.0",
+            uri=path.resolve().as_uri(),
+            sha256=digest.hexdigest(),
+            size_bytes=size,
+            format=format_name,
+            media_type={
+                "arrow": "application/vnd.apache.arrow.file",
+                "parquet": "application/vnd.apache.parquet",
+                "jsonl": "application/x-ndjson",
+                "json": "application/json",
+            }[format_name],
+        )
+    )
+
+
+def snapshot(
+    value: ArrowInput | ArtifactRef | Path,
+    directory: Path,
+    options: ComparisonOptions,
+    check: Callable[[], None],
+) -> ArtifactRef:
+    require_dependency("pyarrow", "arrow")
+    import pyarrow as pa
+
+    if isinstance(value, ArrowInput):
+        if not isinstance(value.table, pa.Table):
+            raise TypeError("ArrowInput requires an Arrow Table")
+        path = directory / (uuid4().hex + ".arrow")
+        try:
+            with path.open("xb") as sink, pa.ipc.new_file(sink, value.table.schema) as writer:
+                for batch in value.table.to_reader(max_chunksize=options.batch_rows):
+                    check()
+                    if batch.nbytes > options.max_batch_bytes:
+                        raise ResourceLimitError("max_batch_bytes")
+                    batch.validate(full=True)
+                    writer.write_batch(batch)
+                    sink.flush()
+                    check()
+            return file_ref(path, "arrow", check=check)
+        except BaseException:
+            path.unlink(missing_ok=True)
+            raise
+    ref = ArtifactRef.model_validate(value) if isinstance(value, ArtifactRef) else None
+    source = local_path(ref) if ref else value
+    if not isinstance(source, Path):
+        raise TypeError("comparison input requires ArrowInput, ArtifactRef, or Path")
+    format_name = (
+        ref.format if ref else {".arrow": "arrow", ".parquet": "parquet"}.get(source.suffix.lower())
+    )
+    if format_name not in ("arrow", "parquet"):
+        raise CapabilityError("comparison supports local Arrow IPC file and Parquet")
+    path = directory / (uuid4().hex + "." + format_name)
+    digest = hashlib.sha256()
+    size = 0
+    try:
+        with source.open("rb") as reader, path.open("xb") as writer:
+            while block := reader.read(min(1024 * 1024, options.max_disk_bytes + 1)):
+                check()
+                writer.write(block)
+                writer.flush()
+                digest.update(block)
+                size += len(block)
+                check()
+        if ref and (size != ref.size_bytes or digest.hexdigest() != ref.sha256):
+            raise ArtifactIntegrityError("artifact SHA-256 or size mismatch")
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+    return ArtifactRef.model_validate(
+        dict(
+            schema_version="1.0",
+            uri=path.resolve().as_uri(),
+            sha256=digest.hexdigest(),
+            size_bytes=size,
+            format=format_name,
+            media_type="application/vnd.apache.arrow.file"
+            if format_name == "arrow"
+            else "application/vnd.apache.parquet",
+        )
+    )
+
+
+@contextmanager
+def batches(
+    ref: ArtifactRef, options: ComparisonOptions, check: Callable[[], None]
+) -> Iterator[tuple[pa.Schema, Iterator[pa.RecordBatch]]]:
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+
+    with local_path(ref).open("rb") as source:
+        if ref.format == "parquet":
+            with pq.ParquetFile(source) as reader:
+                yield (
+                    reader.schema_arrow,
+                    _checked(
+                        reader.iter_batches(batch_size=options.batch_rows, use_threads=False),
+                        options,
+                        check,
+                    ),
+                )
+        else:
+            reader = pa.ipc.open_file(source)
+
+            def iterate() -> Iterator[pa.RecordBatch]:
+                for index in range(reader.num_record_batches):
+                    check()
+                    batch = reader.get_batch(index)
+                    # IPC file batches are indivisible at decode time. This check
+                    # is cooperative and follows decode; never a process RSS quota.
+                    if batch.nbytes > options.max_batch_bytes:
+                        raise ResourceLimitError("IPC stored batch exceeds max_batch_bytes")
+                    for start in range(0, batch.num_rows, options.batch_rows):
+                        yield batch.slice(start, options.batch_rows)
+
+            yield reader.schema, _checked(iterate(), options, check)
+
+
+def _checked(
+    iterator: Iterator[pa.RecordBatch], options: ComparisonOptions, check: Callable[[], None]
+) -> Iterator[pa.RecordBatch]:
+    for batch in iterator:
+        check()
+        if batch.nbytes > options.max_batch_bytes:
+            raise ResourceLimitError("max_batch_bytes")
+        batch.validate(full=True)
+        yield batch

equiframe/_dataset_provenance.py

@@ -0,0 +1,146 @@
+"""Versioned source and content identities for the convenience file reader."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from typing import Any, cast
+
+from equiframe.errors import InvalidExecutionInput
+
+
+def _digest(value: str) -> None:
+    if not isinstance(value, str) or re.fullmatch(r"[0-9a-f]{64}", value) is None:
+        raise ValueError("A lowercase SHA-256 identity is required")
+
+
+@dataclass(frozen=True)
+class DatasetSource:
+    """Identity of the exact bytes consumed, plus the effective reader options."""
+
+    uri: str
+    format: str
+    sha256: str
+    size_bytes: int
+    read_options_json: str
+    schema_version: str = "1.0"
+
+    def __post_init__(self) -> None:
+        _digest(self.sha256)
+        if self.schema_version != "1.0" or not self.uri:
+            raise ValueError("Unknown dataset source version or missing URI")
+        if type(self.size_bytes) is not int or self.size_bytes < 0:
+            raise ValueError("Source size must be a nonnegative integer")
+        if not isinstance(json.loads(self.read_options_json), dict):
+            raise ValueError("Reader options must be an object")
+
+    @property
+    def read_options(self) -> dict[str, Any]:
+        # Return a new object so a caller cannot mutate the recorded options.
+        return cast("dict[str, Any]", json.loads(self.read_options_json))
+
+    def to_dict(self) -> dict[str, Any]:
+        result = asdict(self)
+        result["read_options"] = result.pop("read_options_json")
+        result["read_options"] = self.read_options
+        return result
+
+
+@dataclass(frozen=True)
+class DatasetProvenance:
+    """One source snapshot -> original Pandas snapshot -> native destination."""
+
+    source: DatasetSource
+    pandas_sha256: str
+    target: str
+    target_sha256: str
+    fingerprint_version: str = "equiframe-dataset-content-1.0"
+
+    def __post_init__(self) -> None:
+        _digest(self.pandas_sha256)
+        _digest(self.target_sha256)
+        if self.target not in ("pandas", "polars", "duckdb"):
+            raise ValueError("Unknown dataset destination")
+        if self.fingerprint_version != "equiframe-dataset-content-1.0":
+            raise ValueError("Unknown dataset fingerprint version")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source.to_dict(),
+            "pandas_sha256": self.pandas_sha256,
+            "target": self.target,
+            "target_sha256": self.target_sha256,
+            "fingerprint_version": self.fingerprint_version,
+        }
+
+
+def _value(value: Any, pandas: Any) -> Any:
+    if value is None:
+        return ["null"]
+    if value is pandas.NA:
+        return ["pandas_na"]
+    if value is pandas.NaT:
+        return ["pandas_nat"]
+    if isinstance(value, bool):
+        return ["boolean", value]
+    if isinstance(value, int):
+        return ["integer", str(value)]
+    if isinstance(value, float):
+        return ["float", "nan" if math.isnan(value) else value.hex()]
+    if isinstance(value, Decimal):
+        return ["decimal", str(value)]
+    if isinstance(value, str):
+        return ["string", value]
+    if isinstance(value, bytes):
+        return ["binary", value.hex()]
+    if isinstance(value, datetime):
+        return ["timestamp", value.isoformat(), value.fold]
+    if isinstance(value, (date, time)):
+        return [type(value).__name__, value.isoformat()]
+    if isinstance(value, pandas.Timedelta):
+        return ["duration_ns", str(value.value)]
+    if isinstance(value, timedelta):
+        return ["duration", value.days, value.seconds, value.microseconds]
+    if isinstance(value, Mapping):
+        return [
+            "object",
+            [[_value(key, pandas), _value(item, pandas)] for key, item in value.items()],
+        ]
+    if isinstance(value, (list, tuple)):
+        return ["array", [_value(item, pandas) for item in value]]
+    raise InvalidExecutionInput("Dataset values cannot be fingerprinted without conversion")
+
+
+def _update(digest: Any, value: Any) -> None:
+    digest.update(
+        json.dumps(value, ensure_ascii=True, allow_nan=False, separators=(",", ":")).encode("ascii")
+    )
+    digest.update(b"\n")
+
+
+def pandas_fingerprint(frame: Any, pandas: Any) -> str:
+    """Identify every observed value and native dtype, without sampling."""
+    digest = hashlib.sha256()
+    _update(digest, ["equiframe-dataset-content-1.0", "pandas", len(frame)])
+    for name in frame.columns:
+        _update(digest, [name, str(frame[name].dtype)])
+        for value in frame[name].tolist():
+            _update(digest, _value(value, pandas))
+    return digest.hexdigest()
+
+
+def arrow_fingerprint(table: Any, pandas: Any) -> str:
+    digest = hashlib.sha256()
+    _update(digest, ["equiframe-dataset-content-1.0", "arrow", table.num_rows])
+    for field, column in zip(table.schema, table.columns, strict=False):
+        _update(digest, [field.name, str(field.type), field.nullable])
+        for chunk in column.chunks:
+            for scalar in chunk:
+                _update(digest, _value(scalar.as_py(), pandas))
+    return digest.hexdigest()

equiframe/_decimal.py

@@ -0,0 +1,22 @@
+"""Isolated arithmetic for bounded exact decimals, independent of consumer state."""
+
+from decimal import ROUND_HALF_EVEN, Context, DivisionByZero, InvalidOperation, Overflow
+
+
+def exact_decimal_context() -> Context:
+    """Create fresh settings and flags; callers retain their own context unchanged.
+
+    One hundred digits exceed the 76-digit Arrow decimal contract and the common
+    38-digit native IR. Rounding is never permission to lose precision: ingestion
+    and IR validation compare quantized values with their exact source values.
+    """
+    return Context(
+        prec=100,
+        rounding=ROUND_HALF_EVEN,
+        Emin=-999999,
+        Emax=999999,
+        capitals=1,
+        clamp=0,
+        flags=[],
+        traps=[InvalidOperation, DivisionByZero, Overflow],
+    )