rowguard 0.1.0__py3-none-any.whl

rowguard/__init__.py

@@ -0,0 +1,31 @@
+from rowguard.api import execute, select, stream, validate_rows
+from rowguard.errors import (
+    ConfigurationError,
+    QueryExecutionError,
+    RejectHandlerError,
+    RowAdaptationError,
+    RowGuardError,
+    RowValidationError,
+)
+from rowguard.results.query_result import QueryResult
+from rowguard.results.rejected_row import RejectedRow
+from rowguard.statistics import QueryStatistics
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ConfigurationError",
+    "QueryExecutionError",
+    "QueryResult",
+    "QueryStatistics",
+    "RejectHandlerError",
+    "RejectedRow",
+    "RowAdaptationError",
+    "RowGuardError",
+    "RowValidationError",
+    "__version__",
+    "execute",
+    "select",
+    "stream",
+    "validate_rows",
+]

rowguard/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Row adapter protocols and implementations."""
+
+from rowguard.adapters.base import AdaptedRow, RowAdapter
+from rowguard.adapters.sqlalchemy_row import SQLAlchemyRowAdapter
+
+__all__ = ["AdaptedRow", "RowAdapter", "SQLAlchemyRowAdapter"]

rowguard/adapters/base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class AdaptedRow:
+    mapping: Mapping[str, object]
+    raw_row: object | None = None
+
+
+class RowAdapter(Protocol):
+    def adapt(self, row: object) -> AdaptedRow: ...

rowguard/adapters/sqlalchemy_row.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from rowguard.adapters.base import AdaptedRow
+from rowguard.errors import RowAdaptationError
+
+
+class SQLAlchemyRowAdapter:
+    """Adapt SQLAlchemy rows or mappings into Pydantic-ready dictionaries."""
+
+    def __init__(self, field_map: Mapping[str, str] | None = None) -> None:
+        self._field_map = dict(field_map) if field_map else None
+
+    def adapt(self, row: object) -> AdaptedRow:
+        source = getattr(row, "_mapping", None)
+        if source is None:
+            if isinstance(row, Mapping):
+                source = row
+            else:
+                raise RowAdaptationError(f"Unsupported row type: {type(row).__name__}")
+
+        mapping: dict[str, object] = dict(source)
+        if self._field_map is not None:
+            remapped: dict[str, object] = {}
+            missing: list[str] = []
+            for field_name, column_key in self._field_map.items():
+                if column_key not in mapping:
+                    missing.append(f"{field_name}->{column_key}")
+                    continue
+                remapped[field_name] = mapping[column_key]
+            if missing:
+                raise RowAdaptationError(
+                    "field_map source key(s) missing from row: " + ", ".join(missing)
+                )
+
+            reserved_sources = set(self._field_map.values())
+            reserved_destinations = set(self._field_map.keys())
+            for key, value in mapping.items():
+                if key in reserved_sources or key in reserved_destinations:
+                    continue
+                if key not in remapped:
+                    remapped[key] = value
+            mapping = remapped
+
+        return AdaptedRow(mapping=mapping, raw_row=row)

rowguard/api.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+from sqlalchemy.sql import Select
+
+from rowguard.adapters.sqlalchemy_row import SQLAlchemyRowAdapter
+from rowguard.errors import ConfigurationError
+from rowguard.execution.sync import SyncExecutionEngine
+from rowguard.planning.compiler import QueryPlanner
+from rowguard.planning.execution_plan import ExecutionPlan
+from rowguard.planning.request import QueryRequest
+from rowguard.rejection.base import RejectionPolicy
+from rowguard.rejection.policies import CollectPolicy, RaisePolicy, SkipPolicy
+from rowguard.results.query_result import QueryResult
+from rowguard.validation.pydantic import PydanticValidator
+
+T = TypeVar("T", bound=BaseModel)
+
+_POLICIES: dict[str, type[RejectionPolicy]] = {
+    "raise": RaisePolicy,
+    "collect": CollectPolicy,
+    "skip": SkipPolicy,
+}
+
+
+def select(
+    *,
+    session: Any | None = None,
+    connection: Any | None = None,
+    table: Any,
+    model: type[T],
+    where: Iterable[Any] = (),
+    field_map: Mapping[str, str] | None = None,
+    column_map: Mapping[str, Any] | None = None,
+    parameters: Mapping[str, object] | None = None,
+    on_reject: str = "raise",
+    use_sqlrules: bool = True,
+) -> QueryResult[T]:
+    """Build and execute a validation-first SQLAlchemy SELECT query."""
+    request: QueryRequest[T] = QueryRequest(
+        model=model,
+        source=table,
+        session=session,
+        connection=connection,
+        where=tuple(where),
+        field_map=field_map,
+        column_map=column_map,
+        parameters=dict(parameters or {}),
+        on_reject=on_reject,
+        use_sqlrules=use_sqlrules,
+    )
+    plan = QueryPlanner[T]().compile(request)
+    return SyncExecutionEngine[T]().execute(plan)
+
+
+def execute(
+    *,
+    session: Any | None = None,
+    connection: Any | None = None,
+    statement: Select[Any],
+    model: type[T],
+    source: Any | None = None,
+    where: Iterable[Any] = (),
+    field_map: Mapping[str, str] | None = None,
+    column_map: Mapping[str, Any] | None = None,
+    parameters: Mapping[str, object] | None = None,
+    on_reject: str = "raise",
+    use_sqlrules: bool = True,
+) -> QueryResult[T]:
+    """Execute an existing SQLAlchemy statement and validate every row."""
+    request: QueryRequest[T] = QueryRequest(
+        model=model,
+        source=source,
+        statement=statement,
+        session=session,
+        connection=connection,
+        where=tuple(where),
+        field_map=field_map,
+        column_map=column_map,
+        parameters=dict(parameters or {}),
+        on_reject=on_reject,
+        use_sqlrules=use_sqlrules,
+    )
+    plan = QueryPlanner[T]().compile(request)
+    return SyncExecutionEngine[T]().execute(plan)
+
+
+def stream(
+    *,
+    session: Any,
+    statement: Select[Any],
+    model: type[T],
+    on_reject: str = "raise",
+) -> Iterable[T]:
+    """Stream validated models without buffering all accepted rows.
+
+    Deferred until 0.3.0.
+    """
+    raise NotImplementedError(
+        "stream() is deferred to RowGuard 0.3.0; use select()/execute() for buffered results"
+    )
+
+
+def validate_rows(
+    *,
+    rows: Iterable[Mapping[str, object]],
+    model: type[T],
+    field_map: Mapping[str, str] | None = None,
+    on_reject: str = "raise",
+) -> QueryResult[T]:
+    """Validate row mappings without executing SQL."""
+    policy_cls = _POLICIES.get(on_reject)
+    if policy_cls is None:
+        raise ConfigurationError(
+            f"Unsupported on_reject policy: {on_reject!r}. "
+            f"Supported: {', '.join(sorted(_POLICIES))}"
+        )
+
+    plan: ExecutionPlan[T] = ExecutionPlan(
+        statement=None,
+        model=model,
+        adapter=SQLAlchemyRowAdapter(field_map=field_map),
+        validator=PydanticValidator(model),
+        rejection_policy=policy_cls(),
+        use_sqlrules=False,
+    )
+    return SyncExecutionEngine[T]().validate_rows(plan=plan, rows=rows)

rowguard/cache.py

@@ -0,0 +1,26 @@
+from collections import OrderedDict
+from typing import Generic, TypeVar
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class LRUCache(Generic[K, V]):
+    def __init__(self, max_entries: int = 512) -> None:
+        self._max_entries = max_entries
+        self._items: OrderedDict[K, V] = OrderedDict()
+
+    def get(self, key: K) -> V | None:
+        value = self._items.get(key)
+        if value is not None:
+            self._items.move_to_end(key)
+        return value
+
+    def set(self, key: K, value: V) -> None:
+        self._items[key] = value
+        self._items.move_to_end(key)
+        while len(self._items) > self._max_entries:
+            self._items.popitem(last=False)
+
+    def clear(self) -> None:
+        self._items.clear()

rowguard/diagnostics.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    code: str
+    severity: str
+    execution_id: str
+    row_index: int | None = None
+    metadata: Mapping[str, object] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

rowguard/errors.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError
+
+
+class RowGuardError(Exception):
+    """Base exception for all RowGuard errors."""
+
+
+class ConfigurationError(RowGuardError):
+    """Invalid or incompatible RowGuard configuration."""
+
+
+class QueryExecutionError(RowGuardError):
+    """SQLAlchemy query execution failed."""
+
+
+class RowAdaptationError(RowGuardError):
+    """A database row could not be adapted safely."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        model: type[Any] | None = None,
+        row_index: int | None = None,
+    ) -> None:
+        self.model = model
+        self.row_index = row_index
+        super().__init__(message)
+
+
+class RowValidationError(RowGuardError):
+    """A row failed Pydantic validation under the raise policy."""
+
+    def __init__(
+        self,
+        *,
+        model: type[Any],
+        validation_error: ValidationError,
+        row_index: int | None = None,
+    ) -> None:
+        self.model = model
+        self.validation_error = validation_error
+        self.row_index = row_index
+        super().__init__(
+            f"Row {row_index!r} failed validation for {model.__name__} "
+            f"with {validation_error.error_count()} error(s)."
+        )
+
+
+class RejectHandlerError(RowGuardError):
+    """A rejection callback or quarantine provider failed."""
+
+
+class ResultAssemblyError(RowGuardError):
+    """An inconsistent public result was about to be created."""

rowguard/execution/__init__.py

@@ -0,0 +1,6 @@
+"""Execution engines and per-row processing."""
+
+from rowguard.execution.processor import ProcessedRow, process_row
+from rowguard.execution.sync import SyncExecutionEngine
+
+__all__ = ["ProcessedRow", "SyncExecutionEngine", "process_row"]

rowguard/execution/processor.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import perf_counter_ns
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+from rowguard.errors import RowAdaptationError
+from rowguard.planning.execution_plan import ExecutionPlan
+from rowguard.rejection.base import RejectionDecision
+from rowguard.results.rejected_row import RejectedRow
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessedRow(Generic[T]):
+    model: T | None
+    rejected: RejectedRow | None
+    retain_rejection: bool
+    continue_processing: bool
+    adaptation_time_ns: int = 0
+    validation_time_ns: int = 0
+    rejection_time_ns: int = 0
+    validated: bool = False
+
+
+def process_row(
+    *,
+    row: object,
+    index: int,
+    plan: ExecutionPlan[T],
+) -> ProcessedRow[T]:
+    """Adapt, validate, and apply rejection policy for a single row."""
+    adaptation_time_ns = 0
+    validation_time_ns = 0
+
+    started = perf_counter_ns()
+    try:
+        adapted = plan.adapter.adapt(row)
+    except RowAdaptationError as error:
+        adaptation_time_ns = perf_counter_ns() - started
+        rejected = RejectedRow(
+            index=index,
+            model=plan.model,
+            mapping=None,
+            validation_error=None,
+            adaptation_error=error,
+            raw_row=row,
+        )
+        return _handle_rejection(
+            plan,
+            rejected,
+            adaptation_time_ns=adaptation_time_ns,
+            validated=False,
+        )
+    adaptation_time_ns = perf_counter_ns() - started
+
+    started = perf_counter_ns()
+    outcome = plan.validator.validate(adapted.mapping)
+    validation_time_ns = perf_counter_ns() - started
+
+    if outcome.accepted:
+        assert outcome.model is not None
+        return ProcessedRow(
+            model=outcome.model,
+            rejected=None,
+            retain_rejection=False,
+            continue_processing=True,
+            adaptation_time_ns=adaptation_time_ns,
+            validation_time_ns=validation_time_ns,
+            validated=True,
+        )
+
+    rejected = RejectedRow(
+        index=index,
+        model=plan.model,
+        mapping=adapted.mapping,
+        validation_error=outcome.error,
+        raw_row=adapted.raw_row,
+    )
+    return _handle_rejection(
+        plan,
+        rejected,
+        adaptation_time_ns=adaptation_time_ns,
+        validation_time_ns=validation_time_ns,
+        validated=True,
+    )
+
+
+def _handle_rejection(
+    plan: ExecutionPlan[T],
+    rejected: RejectedRow,
+    *,
+    adaptation_time_ns: int = 0,
+    validation_time_ns: int = 0,
+    validated: bool = False,
+) -> ProcessedRow[T]:
+    started = perf_counter_ns()
+    decision: RejectionDecision = plan.rejection_policy.handle(rejected)
+    rejection_time_ns = perf_counter_ns() - started
+    return ProcessedRow(
+        model=None,
+        rejected=rejected,
+        retain_rejection=decision.retain_rejection,
+        continue_processing=decision.continue_processing,
+        adaptation_time_ns=adaptation_time_ns,
+        validation_time_ns=validation_time_ns,
+        rejection_time_ns=rejection_time_ns,
+        validated=validated,
+    )

rowguard/execution/streaming.py

@@ -0,0 +1,14 @@
+from collections.abc import Iterator
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class StreamResult(Generic[T], Iterator[T]):
+    def __iter__(self) -> "StreamResult[T]":
+        return self
+
+    def __next__(self) -> T:
+        raise StopIteration

rowguard/execution/sync.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from time import perf_counter_ns
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from rowguard.diagnostics import Diagnostic
+from rowguard.errors import QueryExecutionError, ResultAssemblyError, RowGuardError
+from rowguard.execution.processor import ProcessedRow, process_row
+from rowguard.planning.execution_plan import ExecutionPlan
+from rowguard.results.query_result import QueryResult
+from rowguard.results.rejected_row import RejectedRow
+from rowguard.statistics import QueryStatistics
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@dataclass(slots=True)
+class _MutableStatistics:
+    rows_read: int = 0
+    rows_validated: int = 0
+    rows_accepted: int = 0
+    rows_rejected: int = 0
+    execution_time_ns: int = 0
+    adaptation_time_ns: int = 0
+    validation_time_ns: int = 0
+    rejection_time_ns: int = 0
+
+    def snapshot(self) -> QueryStatistics:
+        return QueryStatistics(
+            rows_read=self.rows_read,
+            rows_validated=self.rows_validated,
+            rows_accepted=self.rows_accepted,
+            rows_rejected=self.rows_rejected,
+            execution_time_ns=self.execution_time_ns,
+            adaptation_time_ns=self.adaptation_time_ns,
+            validation_time_ns=self.validation_time_ns,
+            rejection_time_ns=self.rejection_time_ns,
+        )
+
+
+@dataclass(slots=True)
+class ExecutionState(Generic[T]):
+    plan: ExecutionPlan[T]
+    statistics: _MutableStatistics = field(default_factory=_MutableStatistics)
+    accepted: list[T] = field(default_factory=list)
+    rejected: list[RejectedRow] = field(default_factory=list)
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+
+
+class SyncExecutionEngine(Generic[T]):
+    def execute(self, plan: ExecutionPlan[T]) -> QueryResult[T]:
+        state = ExecutionState(plan=plan)
+        state.diagnostics.extend(plan.diagnostics)
+        started = perf_counter_ns()
+        result: Any | None = None
+
+        try:
+            result = self._execute_statement(plan)
+            for index, row in enumerate(result):
+                processed = process_row(row=row, index=index, plan=plan)
+                if not self._consume_processed(state, processed):
+                    break
+        except RowGuardError:
+            raise
+        except Exception as exc:
+            raise QueryExecutionError(f"Query execution failed: {exc}") from exc
+        finally:
+            if result is not None:
+                close = getattr(result, "close", None)
+                if callable(close):
+                    close()
+            state.statistics.execution_time_ns = perf_counter_ns() - started
+
+        return self._assemble(state)
+
+    def validate_rows(
+        self,
+        *,
+        plan: ExecutionPlan[T],
+        rows: Iterable[Mapping[str, object]],
+    ) -> QueryResult[T]:
+        state = ExecutionState(plan=plan)
+        state.diagnostics.extend(plan.diagnostics)
+        started = perf_counter_ns()
+
+        try:
+            for index, row in enumerate(rows):
+                processed = process_row(row=row, index=index, plan=plan)
+                if not self._consume_processed(state, processed):
+                    break
+        finally:
+            state.statistics.execution_time_ns = perf_counter_ns() - started
+
+        return self._assemble(state)
+
+    def _consume_processed(
+        self,
+        state: ExecutionState[T],
+        processed: ProcessedRow[T],
+    ) -> bool:
+        """Update state from a processed row. Returns whether to continue."""
+        state.statistics.rows_read += 1
+        state.statistics.adaptation_time_ns += processed.adaptation_time_ns
+        state.statistics.validation_time_ns += processed.validation_time_ns
+        state.statistics.rejection_time_ns += processed.rejection_time_ns
+        if processed.validated:
+            state.statistics.rows_validated += 1
+
+        if processed.model is not None:
+            state.statistics.rows_accepted += 1
+            state.accepted.append(processed.model)
+            return True
+
+        state.statistics.rows_rejected += 1
+        if processed.retain_rejection and processed.rejected is not None:
+            state.rejected.append(processed.rejected)
+        return processed.continue_processing
+
+    def _execute_statement(self, plan: ExecutionPlan[T]) -> Any:
+        params = dict(plan.parameters) if plan.parameters else {}
+        if plan.session is not None:
+            if params:
+                return plan.session.execute(plan.statement, params)
+            return plan.session.execute(plan.statement)
+        if plan.connection is not None:
+            if params:
+                return plan.connection.execute(plan.statement, params)
+            return plan.connection.execute(plan.statement)
+        raise QueryExecutionError("No session or connection available for execution")
+
+    def _assemble(self, state: ExecutionState[T]) -> QueryResult[T]:
+        stats = state.statistics.snapshot()
+        if stats.rows_accepted != len(state.accepted):
+            raise ResultAssemblyError("Accepted count does not match models")
+        if stats.rows_rejected < len(state.rejected):
+            raise ResultAssemblyError("Rejected count is less than retained rejections")
+        if stats.rows_accepted + stats.rows_rejected != stats.rows_read:
+            raise ResultAssemblyError("Read rows are not fully classified")
+        if stats.rows_validated > stats.rows_read:
+            raise ResultAssemblyError("Validated count exceeds rows read")
+
+        return QueryResult(
+            models=tuple(state.accepted),
+            rejected=tuple(state.rejected),
+            statistics=stats,
+            statement=state.plan.statement,
+            diagnostics=tuple(state.diagnostics),
+        )

rowguard/integrations/__init__.py

@@ -0,0 +1,11 @@
+"""Database and SQLRules integrations."""
+
+from rowguard.integrations.sqlalchemy_core import apply_where, build_select
+from rowguard.integrations.sqlrules import CompiledPushdown, SQLRulesBridge
+
+__all__ = [
+    "CompiledPushdown",
+    "SQLRulesBridge",
+    "apply_where",
+    "build_select",
+]

rowguard/integrations/sqlalchemy_core.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, cast
+
+from sqlalchemy import Select, select
+from sqlalchemy.sql import ColumnElement
+
+
+def build_select(source: object) -> Select[Any]:
+    """Build a SELECT over a Core table or selectable."""
+    return cast(Select[Any], select(source))  # type: ignore[call-overload]
+
+
+def apply_where(statement: Select[Any], expressions: Iterable[object]) -> Select[Any]:
+    """Return a new statement with additional WHERE expressions."""
+    exprs = tuple(expressions)
+    if not exprs:
+        return statement
+    return statement.where(*exprs)  # type: ignore[arg-type]
+
+
+def is_select(value: object) -> bool:
+    return isinstance(value, Select)
+
+
+def is_column_element(value: object) -> bool:
+    return isinstance(value, ColumnElement)

rowguard/integrations/sqlalchemy_orm.py

@@ -0,0 +1,5 @@
+"""Deferred ORM integration.
+
+Milestone 0.1.0 should focus on SQLAlchemy Core. Keep this module as the future
+boundary for mapped-class and entity adaptation.
+"""

rowguard/integrations/sqlmodel.py

@@ -0,0 +1,5 @@
+"""Deferred SQLModel integration.
+
+SQLModel remains responsible for mapping and persistence. RowGuard will add
+explicit validation-first query execution in a later milestone.
+"""