rowguard 0.1.0__tar.gz

rowguard-0.1.0/.github/workflows/benchmarks.yml

@@ -0,0 +1,23 @@
+name: Benchmarks
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pytest benchmarks --benchmark-only --benchmark-json=benchmark.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: benchmark.json

rowguard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,async]"
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Mypy
+        run: mypy src/rowguard
+
+      - name: Pytest
+        run: pytest --cov=rowguard --cov-report=term-missing
+
+      - name: Example smoke
+        run: python examples/basic.py
+
+  benchmark-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pytest benchmarks --benchmark-only

rowguard-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    name: Commit checks
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: ci
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Verify tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ["GITHUB_REF_NAME"]
+          assert tag.startswith("v"), tag
+          expected = tag[1:]
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          init = Path("src/rowguard/__init__.py").read_text()
+          marker = '__version__ = "'
+          start = init.index(marker) + len(marker)
+          end = init.index('"', start)
+          init_version = init[start:end]
+          assert version == expected == init_version, (version, expected, init_version)
+          print(f"tag/version ok: {tag} -> {version}")
+          PY
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Twine check
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

rowguard-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Bytecode / caches
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+.benchmarks/
+
+# Tooling
+.pre-commit/
+*.log
+.DS_Store
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*~

rowguard-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.7
+          - SQLAlchemy>=2.0
+          - sqlrules>=0.2.0
+        args: [--config-file=pyproject.toml]
+        pass_filenames: false

rowguard-0.1.0/API.md

@@ -0,0 +1,177 @@
+# API.md
+
+# RowGuard Public API
+
+## Philosophy
+
+The public API is intentionally small. RowGuard should expose a few
+powerful, composable entry points while keeping execution details
+internal.
+
+## Core Functions
+
+### select()
+
+Execute a SQL query, validate every returned row against a Pydantic
+model, and return a `QueryResult`.
+
+``` python
+result = rowguard.select(
+    session=session,
+    table=users,
+    model=UserRead,
+    where=(),
+    field_map=None,
+    column_map=None,
+    parameters=None,
+    on_reject="raise",
+    use_sqlrules=True,
+)
+```
+
+Parameters:
+
+-   `session` or `connection`: exactly one SQLAlchemy execution context
+-   `table`: SQLAlchemy Core `Table` or selectable
+-   `model`: Pydantic `BaseModel` subclass
+-   `where`: optional additional SQLAlchemy expressions (default `()`)
+-   `field_map`: optional model-field → result-key mapping
+-   `column_map`: optional model-field → SQLAlchemy column mapping for SQLRules
+-   `parameters`: optional bound parameters forwarded to SQLAlchemy
+-   `on_reject`: `raise`, `collect`, or `skip`
+    (`callback` / `quarantine` / `log` planned for later releases)
+-   `use_sqlrules`: enable SQLRules constraint pushdown (default `True`)
+
+Returns:
+
+``` python
+QueryResult[UserRead]
+```
+
+------------------------------------------------------------------------
+
+### stream()
+
+Validate rows incrementally while streaming large result sets.
+
+> **Status (0.1.0):** Not implemented. Raises `NotImplementedError`.
+> Planned for 0.3.0.
+
+``` python
+for model in rowguard.stream(
+    session=session,
+    statement=stmt,
+    model=UserRead,
+):
+    ...
+```
+
+------------------------------------------------------------------------
+
+### execute()
+
+Execute an existing SQLAlchemy statement instead of constructing one.
+
+``` python
+result = rowguard.execute(
+    session=session,
+    statement=stmt,
+    model=UserRead,
+    source=None,
+    on_reject="raise",
+    use_sqlrules=True,
+)
+```
+
+Optional `source=` supplies the selectable used for SQLRules pushdown when
+`use_sqlrules=True`. When both `statement` and `source` are provided, RowGuard
+emits a `sqlrules.pushdown_source_explicit` diagnostic.
+
+------------------------------------------------------------------------
+
+### validate_rows()
+
+Validate an iterable of row mappings without executing SQL.
+
+``` python
+result = rowguard.validate_rows(
+    rows=rows,
+    model=UserRead,
+    field_map=None,
+    on_reject="raise",
+)
+```
+
+Useful for CSV readers, ETL pipelines, or custom data sources.
+
+## QueryResult
+
+``` python
+result.models
+result.rejected
+result.statistics
+result.statement
+result.diagnostics
+result.execution_time
+```
+
+Convenience properties:
+
+``` python
+result.valid_count
+result.rejected_count   # retained rejections only (0 under skip)
+result.has_rejections   # True if any row was rejected (including skip)
+result.is_clean
+```
+
+`has_rejections` is based on `statistics.rows_rejected`, not on whether
+rejected rows were retained. Under `skip`, `has_rejections` may be `True`
+while `rejected` is empty.
+
+`execution_time` is end-to-end wall time in seconds (statement fetch plus
+validation for SQL paths; full processing for `validate_rows`).
+
+## RejectedRow
+
+Each rejected row exposes:
+
+``` python
+rejected.index
+rejected.model
+rejected.mapping
+rejected.validation_error
+rejected.adaptation_error
+rejected.raw_row
+```
+
+## Statistics
+
+`QueryStatistics` fields:
+
+-   `rows_read`
+-   `rows_validated` (rows that reached Pydantic validation)
+-   `rows_accepted`
+-   `rows_rejected`
+-   `execution_time_ns`
+-   `adaptation_time_ns`
+-   `validation_time_ns`
+-   `rejection_time_ns`
+
+## Async API (Planned — 0.4.0)
+
+> Not available in 0.1.0.
+
+``` python
+await rowguard.aselect(...)
+await rowguard.aexecute(...)
+async for model in rowguard.astream(...):
+    ...
+```
+
+## Design Guidelines
+
+-   Return immutable result objects where practical.
+-   Never silently discard invalid rows without counting them.
+-   Keep function names short and predictable.
+-   Prefer explicit configuration over implicit behavior.
+-   Build on SQLAlchemy and SQLRules rather than replacing them.

rowguard-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,265 @@
+# ARCHITECTURE.md
+
+# RowGuard Architecture
+
+## Overview
+
+RowGuard is a layered validation-first query engine built on top of
+SQLAlchemy, Pydantic, and SQLRules.
+
+Its architecture intentionally separates SQL compilation, query
+execution, row adaptation, validation, rejection handling, and result
+construction.
+
+``` text
+                  Application
+                        │
+                        ▼
+                 RowGuard Public API
+                        │
+        ┌───────────────┼────────────────┐
+        ▼               ▼                ▼
+   Query Builder   Validation Engine   Streaming API
+        │               │                │
+        └───────────────┼────────────────┘
+                        ▼
+                  Execution Engine
+                        │
+                        ▼
+                  SQLAlchemy Engine
+                        │
+                        ▼
+                     Database
+```
+
+------------------------------------------------------------------------
+
+# Architectural Principles
+
+-   Single responsibility per component
+-   SQLAlchemy-native
+-   Pydantic-native
+-   SQLRules for SQL pushdown only
+-   Immutable data flow where practical
+-   Explicit rejection handling
+-   Observable execution
+
+------------------------------------------------------------------------
+
+# Layered Design
+
+## Layer 1 -- Public API
+
+Responsibilities:
+
+-   Accept user requests
+-   Configure execution
+-   Return QueryResult
+
+Representative API:
+
+``` python
+rowguard.select(...)
+rowguard.stream(...)
+rowguard.execute(...)
+rowguard.validate_rows(...)
+```
+
+------------------------------------------------------------------------
+
+## Layer 2 -- Query Builder
+
+Responsibilities:
+
+-   Accept SQLAlchemy objects
+-   Invoke SQLRules
+-   Merge WHERE expressions
+-   Produce executable SQLAlchemy statements
+
+Output:
+
+``` text
+SQLAlchemy Select
+```
+
+------------------------------------------------------------------------
+
+## Layer 3 -- Execution Engine
+
+Responsibilities:
+
+-   Execute statements
+-   Iterate database rows
+-   Support sync and async execution
+-   Support streaming
+
+The execution engine never performs validation itself.
+
+------------------------------------------------------------------------
+
+## Layer 4 -- Row Adapter
+
+Responsibilities:
+
+-   Convert SQLAlchemy rows into mappings
+-   Preserve column names
+-   Apply aliases when configured
+
+Output:
+
+``` python
+dict[str, object]
+```
+
+------------------------------------------------------------------------
+
+## Layer 5 -- Validation Engine
+
+Responsibilities:
+
+-   Call `model_validate()`
+-   Produce typed Pydantic models
+-   Capture ValidationError objects
+-   Forward failures to rejection handling
+
+Validation remains entirely delegated to Pydantic.
+
+------------------------------------------------------------------------
+
+## Layer 6 -- Rejection Handling
+
+Responsibilities:
+
+-   Raise
+-   Collect
+-   Skip
+-   Log
+-   Callback
+-   Quarantine
+
+Every rejected row follows the configured policy.
+
+------------------------------------------------------------------------
+
+## Layer 7 -- Result Assembly
+
+Produces a QueryResult containing:
+
+-   validated models
+-   rejected rows
+-   execution statistics
+-   diagnostics
+-   executed statement
+
+------------------------------------------------------------------------
+
+# SQLRules Integration
+
+``` text
+Pydantic Model
+      │
+      ▼
+SQLRules
+      │
+      ▼
+WHERE Expressions
+      │
+      ▼
+Query Builder
+```
+
+SQLRules is responsible only for SQL-safe constraint compilation.
+
+RowGuard owns execution and validation.
+
+------------------------------------------------------------------------
+
+# Internal Components
+
+``` text
+Public API
+     │
+Compiler Bridge
+     │
+Query Builder
+     │
+Execution Engine
+     │
+Row Adapter
+     │
+Validation Engine
+     │
+Reject Handler
+     │
+Result Assembler
+```
+
+Each component should be independently testable.
+
+------------------------------------------------------------------------
+
+# Query Lifecycle
+
+``` text
+Receive Request
+      │
+Build Statement
+      │
+Compile SQLRules Filters
+      │
+Execute SQL
+      │
+Adapt Row
+      │
+Validate
+      │
+Accept or Reject
+      │
+Return QueryResult
+```
+
+------------------------------------------------------------------------
+
+# Thread Safety
+
+Compiler configuration and registries should be immutable after
+initialization.
+
+Execution state is scoped to each query.
+
+------------------------------------------------------------------------
+
+# Extension Points
+
+Future plugins may provide:
+
+-   row adapters
+-   reject handlers
+-   diagnostics
+-   dialect helpers
+-   result exporters
+
+------------------------------------------------------------------------
+
+# Non-Goals
+
+Architecture intentionally excludes:
+
+-   ORM mapping
+-   migrations
+-   SQL parsing
+-   schema reflection logic
+-   database drivers
+
+------------------------------------------------------------------------
+
+# Design Goals
+
+The architecture should make it easy to:
+
+-   support legacy databases
+-   integrate SQLRules
+-   validate every row
+-   stream millions of rows
+-   add async support
+-   extend behavior without changing the core

rowguard-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-07-10
+
+### Added
+
+- Public sync API: `select()`, `execute()`, `validate_rows()`
+- SQLAlchemy Core support for `Table` and existing `Select`
+- Sync `Session` and `Connection` execution
+- SQLRules pushdown integration (`use_sqlrules`, optional `column_map`)
+- Pydantic v2 row validation via mapping adaptation
+- Rejection policies: `raise`, `collect`, `skip`
+- `QueryResult[T]`, `RejectedRow`, `QueryStatistics`, and diagnostics
+- Optional `field_map` for result key remapping
+- SQLite integration tests, unit tests, CI, and example
+
+### Fixed
+
+- `field_map` no longer silently binds wrong keys or accepts defaults when mapped
+  source columns are missing (raises `RowAdaptationError`)
+- SQLAlchemy results are closed after buffered execution
+- Rows are processed incrementally so `raise` can abort without full prefetch
+- Adaptation failures record timing and enrich `RowAdaptationError` with
+  `row_index` / `model` under the raise policy
+- `execution_time` is end-to-end for SQL and `validate_rows` paths
+- `rows_validated` counts only rows that reached Pydantic validation
+- Explicit `statement` + `source` pushdown emits
+  `sqlrules.pushdown_source_explicit` diagnostic
+- Require `sqlrules>=0.2.0` (needs `Compiler.diagnostics` for pushdown reporting)
+
+### Deferred
+
+- `stream()` (planned for 0.3.0)
+- Async APIs (planned for 0.4.0)
+- ORM / SQLModel integrations
+- Callback and quarantine rejection policies