hayate-sql 0.1.0__py3-none-any.whl

hayate_sql/database.py

@@ -0,0 +1,135 @@
+"""Execution policy shared by the database-native adapters."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .contract import Cardinality, CardinalityError, Query, RowShapeError
+
+type Row = dict[str, Any]
+type Observer = Callable[["QueryEvent"], Awaitable[None] | None]
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    rows_affected: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class QueryEvent:
+    """A parameter-free telemetry event safe to attach to logs and traces."""
+
+    name: str
+    fingerprint: str
+    duration_ms: float
+    succeeded: bool
+    row_count: int | None
+    error_type: str | None
+
+
+class Database(Protocol):
+    async def run(self, query: Query, /, **params: Any) -> object: ...
+
+
+class BaseDatabase(ABC):
+    """Cardinality, timeout, result-shape, and telemetry enforcement.
+
+    Adapters implement only native fetch/execute operations. This deliberately
+    does not define a universal transaction interface.
+    """
+
+    def __init__(self, *, observer: Observer | None = None) -> None:
+        self.observer = observer
+
+    async def run(self, query: Query, /, **params: Any) -> object:
+        values = query.bind(params)
+        started = time.perf_counter()
+        succeeded = False
+        row_count: int | None = None
+        error_type: str | None = None
+        try:
+            if query.timeout_ms is None:
+                result = await self._dispatch(query, values)
+            else:
+                async with asyncio.timeout(query.timeout_ms / 1000):
+                    result = await self._dispatch(query, values)
+            succeeded = True
+            row_count = _row_count(result)
+            return result
+        except BaseException as error:
+            error_type = type(error).__name__
+            raise
+        finally:
+            event = QueryEvent(
+                name=query.name,
+                fingerprint=query.fingerprint,
+                duration_ms=(time.perf_counter() - started) * 1000,
+                succeeded=succeeded,
+                row_count=row_count,
+                error_type=error_type,
+            )
+            await self._observe(event)
+
+    async def _dispatch(self, query: Query, values: Sequence[Any]) -> object:
+        if query.cardinality is Cardinality.EXEC:
+            return await self._execute(query.sql, values)
+
+        rows = await self._fetch(query.sql, values)
+        _validate_rows(query, rows)
+        if query.cardinality is Cardinality.ONE:
+            if len(rows) != 1:
+                raise CardinalityError(f"{query.name}: expected exactly one row, got {len(rows)}")
+            return rows[0]
+        if query.cardinality is Cardinality.MAYBE_ONE:
+            if len(rows) > 1:
+                raise CardinalityError(f"{query.name}: expected at most one row, got {len(rows)}")
+            return rows[0] if rows else None
+        return rows
+
+    async def _observe(self, event: QueryEvent) -> None:
+        if self.observer is None:
+            return
+        try:
+            result = self.observer(event)
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            # Instrumentation must never change query behavior.
+            return
+
+    @abstractmethod
+    async def _fetch(self, sql: str, values: Sequence[Any]) -> list[Row]: ...
+
+    @abstractmethod
+    async def _execute(self, sql: str, values: Sequence[Any]) -> CommandResult: ...
+
+
+def _validate_rows(query: Query, rows: Sequence[Mapping[str, Any]]) -> None:
+    expected = {column.name for column in query.columns}
+    for index, row in enumerate(rows):
+        actual = set(row)
+        if actual != expected:
+            missing = sorted(expected - actual)
+            extra = sorted(actual - expected)
+            details: list[str] = []
+            if missing:
+                details.append(f"missing {', '.join(missing)}")
+            if extra:
+                details.append(f"unexpected {', '.join(extra)}")
+            raise RowShapeError(f"{query.name}: row {index} has {'; '.join(details)}")
+
+
+def _row_count(result: object) -> int | None:
+    if isinstance(result, CommandResult):
+        return result.rows_affected
+    if isinstance(result, list):
+        return len(result)
+    if result is None:
+        return 0
+    return 1

hayate_sql/generate.py

@@ -0,0 +1,173 @@
+"""Generate a typed, dependency-free Python facade from SQL contracts."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from .contract import Cardinality, Query
+from .parser import python_annotation
+
+
+def generate_module(queries: list[Query]) -> str:
+    lines = [
+        '"""Generated by hayate-sql. Do not edit by hand."""',
+        "",
+    ]
+    lines.extend(_imports(queries))
+    lines.extend([""] * (2 if queries and queries[0].cardinality is not Cardinality.EXEC else 1))
+    exported: list[str] = []
+
+    for query in queries:
+        row_type = f"{_pascal_case(query.name)}Row"
+        constant = f"{query.name.upper()}_QUERY"
+        if query.cardinality is not Cardinality.EXEC:
+            lines.append(f"class {row_type}(TypedDict):")
+            for column in query.columns:
+                lines.append(f"    {column.name}: {python_annotation(column.annotation)}")
+            lines.extend(["", ""])
+            exported.append(row_type)
+
+        lines.extend(_query_constant(query, constant))
+        lines.extend(["", ""])
+        lines.extend(_query_function(query, row_type, constant))
+        lines.extend(["", ""])
+        exported.extend([constant, query.name])
+
+    lines.append("__all__ = [")
+    for name in sorted(exported, key=_export_sort_key):
+        lines.append(f"    {_literal(name)},")
+    lines.append("]")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _query_constant(query: Query, constant: str) -> list[str]:
+    lines = [
+        f"{constant} = Query(",
+        f"    name={_literal(query.name)},",
+        "    sql=(",
+    ]
+    for sql_line in query.sql.splitlines(keepends=True):
+        lines.append(f"        {_literal(sql_line)}")
+    lines.extend(
+        [
+            "    ),",
+            f"    cardinality=Cardinality.{_cardinality_member(query.cardinality)},",
+        ]
+    )
+    if query.parameters:
+        lines.append("    parameters=(")
+        for parameter in query.parameters:
+            lines.append(
+                f"        Parameter({_literal(parameter.name)}, {_literal(parameter.annotation)}),"
+            )
+        lines.append("    ),")
+    else:
+        lines.append("    parameters=(),")
+    if query.columns:
+        lines.append("    columns=(")
+        for column in query.columns:
+            lines.append(f"        Column({_literal(column.name)}, {_literal(column.annotation)}),")
+        lines.append("    ),")
+    else:
+        lines.append("    columns=(),")
+    lines.extend(["    timeout_ms=" + repr(query.timeout_ms) + ",", ")"])
+    return lines
+
+
+def _query_function(query: Query, row_type: str, constant: str) -> list[str]:
+    if query.cardinality is Cardinality.ONE:
+        return_type = row_type
+    elif query.cardinality is Cardinality.MAYBE_ONE:
+        return_type = f"{row_type} | None"
+    elif query.cardinality is Cardinality.MANY:
+        return_type = f"list[{row_type}]"
+    else:
+        return_type = "CommandResult"
+
+    if query.parameters:
+        signature = [f"async def {query.name}(", "    db: Database,", "    /,", "    *,"]
+        for parameter in query.parameters:
+            annotation = python_annotation(parameter.annotation)
+            signature.append(f"    {parameter.name}: {annotation},")
+        signature.append(f") -> {return_type}:")
+        call = [
+            "        await db.run(",
+            f"            {constant},",
+            *(f"            {item.name}={item.name}," for item in query.parameters),
+            "        ),",
+        ]
+    else:
+        signature = [f"async def {query.name}(db: Database, /) -> {return_type}:"]
+        call = [f"        await db.run({constant}),"]
+    return [
+        *signature,
+        "    return cast(",
+        f"        {_literal(return_type)},",
+        *call,
+        "    )",
+    ]
+
+
+def _imports(queries: list[Query]) -> list[str]:
+    annotations = {
+        parameter.annotation.removesuffix("?")
+        for query in queries
+        for parameter in query.parameters
+    } | {column.annotation.removesuffix("?") for query in queries for column in query.columns}
+    lines: list[str] = []
+    datetime_types = sorted(annotations & {"date", "datetime"})
+    if datetime_types:
+        lines.append(f"from datetime import {', '.join(datetime_types)}")
+    if "Decimal" in annotations:
+        lines.append("from decimal import Decimal")
+    typing_types = ["cast"]
+    if "Any" in annotations:
+        typing_types.insert(0, "Any")
+    if any(query.cardinality is not Cardinality.EXEC for query in queries):
+        typing_types.insert(-1, "TypedDict")
+    lines.append(f"from typing import {', '.join(typing_types)}")
+    if "UUID" in annotations:
+        lines.append("from uuid import UUID")
+    lines.extend(
+        [
+            "",
+            "from hayate_sql import (",
+            "    Cardinality,",
+            "    Column,",
+            "    CommandResult,",
+            "    Database,",
+            "    Parameter,",
+            "    Query,",
+            ")",
+        ]
+    )
+    return lines
+
+
+def _pascal_case(name: str) -> str:
+    return "".join(part.capitalize() for part in re.split(r"_+", name) if part)
+
+
+def _cardinality_member(cardinality: Cardinality) -> str:
+    return {
+        Cardinality.ONE: "ONE",
+        Cardinality.MAYBE_ONE: "MAYBE_ONE",
+        Cardinality.MANY: "MANY",
+        Cardinality.EXEC: "EXEC",
+    }[cardinality]
+
+
+def _literal(value: str) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _export_sort_key(name: str) -> tuple[int, str]:
+    if name.isupper():
+        group = 0
+    elif name[:1].isupper():
+        group = 1
+    else:
+        group = 2
+    return group, name

hayate_sql/migrations.py

@@ -0,0 +1,63 @@
+"""Discover ordered, forward-only SQL migrations for disposable schema checks."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_MIGRATION_NAME = re.compile(
+    r"^(?P<version>[0-9]+)_(?P<description>[a-z0-9]+(?:[_-][a-z0-9]+)*)\.sql$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Migration:
+    path: Path
+    version: int
+    version_text: str
+    sql: str
+
+
+def load_migrations(directory: Path) -> list[Migration]:
+    """Load one top-level directory of monotonically numbered SQL migrations."""
+
+    if not directory.is_dir():
+        raise ValueError(f"{directory}: expected a migration directory")
+
+    paths = sorted(directory.glob("*.sql"))
+    if not paths:
+        raise ValueError(f"{directory}: no migration files found")
+
+    migrations: list[Migration] = []
+    versions: dict[int, Path] = {}
+    widths: set[int] = set()
+    for path in paths:
+        matched = _MIGRATION_NAME.fullmatch(path.name)
+        if matched is None:
+            raise ValueError(
+                f"{path}: expected '<number>_<description>.sql' with a lowercase description"
+            )
+
+        version_text = matched.group("version")
+        version = int(version_text)
+        if version == 0:
+            raise ValueError(f"{path}: migration version must be positive")
+        previous = versions.get(version)
+        if previous is not None:
+            raise ValueError(f"duplicate migration version {version}: {previous} and {path}")
+
+        sql = path.read_text(encoding="utf-8")
+        if not sql.strip():
+            raise ValueError(f"{path}: migration SQL cannot be empty")
+
+        versions[version] = path
+        widths.add(len(version_text))
+        migrations.append(Migration(path, version, version_text, sql))
+
+    if len(widths) != 1:
+        raise ValueError(
+            f"{directory}: migration versions must use one fixed width for deterministic ordering"
+        )
+
+    return sorted(migrations, key=lambda migration: migration.version)

hayate_sql/parser.py

@@ -0,0 +1,153 @@
+"""Parser for one-query-per-file SQL contracts."""
+
+from __future__ import annotations
+
+import keyword
+import re
+from pathlib import Path
+
+from .contract import Cardinality, Column, Parameter, Query
+
+_NAME = re.compile(r"^\s*--\s*name:\s*([a-z][a-z0-9]*(?:_[a-z0-9]+)*)\s+:(one\?|one|many|exec)\s*$")
+_PARAM = re.compile(
+    r"^\s*--\s*param:\s*([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z][A-Za-z0-9_]*(?:\?)?)\s*$"
+)
+_COLUMN = re.compile(
+    r"^\s*--\s*column:\s*([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z][A-Za-z0-9_]*(?:\?)?)\s*$"
+)
+_TIMEOUT = re.compile(r"^\s*--\s*timeout:\s*(\d+)(ms|s)\s*$")
+_DIRECTIVE = re.compile(r"^\s*--\s*(name|param|column|timeout):")
+_ALLOWED_TYPES = {
+    "Any",
+    "Decimal",
+    "UUID",
+    "bool",
+    "bytes",
+    "date",
+    "datetime",
+    "float",
+    "int",
+    "object",
+    "str",
+}
+
+
+class QueryParseError(ValueError):
+    def __init__(self, source: str, line: int, message: str) -> None:
+        super().__init__(f"{source}:{line}: {message}")
+        self.source = source
+        self.line = line
+        self.message = message
+
+
+def parse_query(text: str, *, source: str = "<string>") -> Query:
+    name: str | None = None
+    cardinality: Cardinality | None = None
+    parameters: list[Parameter] = []
+    columns: list[Column] = []
+    timeout_ms: int | None = None
+    sql_lines: list[str] = []
+    in_header = True
+
+    for line_number, line in enumerate(text.splitlines(keepends=True), 1):
+        matched = _NAME.match(line)
+        if in_header and matched:
+            if name is not None:
+                raise QueryParseError(source, line_number, "duplicate name directive")
+            name = matched.group(1)
+            _validate_identifier(name, source, line_number, "query")
+            cardinality = Cardinality(matched.group(2))
+            continue
+
+        matched = _PARAM.match(line)
+        if in_header and matched:
+            parameter_name, annotation = matched.groups()
+            _validate_identifier(parameter_name, source, line_number, "parameter")
+            _validate_annotation(annotation, source, line_number)
+            parameters.append(Parameter(parameter_name, annotation))
+            continue
+
+        matched = _COLUMN.match(line)
+        if in_header and matched:
+            column_name, annotation = matched.groups()
+            _validate_identifier(column_name, source, line_number, "column")
+            _validate_annotation(annotation, source, line_number)
+            columns.append(Column(column_name, annotation))
+            continue
+
+        matched = _TIMEOUT.match(line)
+        if in_header and matched:
+            if timeout_ms is not None:
+                raise QueryParseError(source, line_number, "duplicate timeout directive")
+            amount = int(matched.group(1))
+            timeout_ms = amount if matched.group(2) == "ms" else amount * 1000
+            if timeout_ms == 0:
+                raise QueryParseError(source, line_number, "timeout must be positive")
+            continue
+
+        if in_header and _DIRECTIVE.match(line):
+            raise QueryParseError(source, line_number, "malformed query directive")
+
+        if line.strip() and not line.lstrip().startswith("--"):
+            in_header = False
+        sql_lines.append(line)
+
+    if name is None or cardinality is None:
+        raise QueryParseError(source, 1, "missing '-- name: query_name :cardinality'")
+
+    sql = "".join(sql_lines).strip()
+    try:
+        return Query(
+            name=name,
+            sql=sql,
+            cardinality=cardinality,
+            parameters=tuple(parameters),
+            columns=tuple(columns),
+            timeout_ms=timeout_ms,
+        )
+    except ValueError as error:
+        raise QueryParseError(source, 1, str(error)) from error
+
+
+def load_queries(paths: list[Path]) -> list[tuple[Path, Query]]:
+    files: list[Path] = []
+    for path in paths:
+        if path.is_dir():
+            files.extend(sorted(path.rglob("*.sql")))
+        elif path.suffix == ".sql":
+            files.append(path)
+        else:
+            raise ValueError(f"{path}: expected a .sql file or directory")
+    if not files:
+        raise ValueError("no .sql query files found")
+
+    loaded = [(path, parse_query(path.read_text(), source=str(path))) for path in files]
+    names: dict[str, Path] = {}
+    for path, query in loaded:
+        previous = names.get(query.name)
+        if previous is not None:
+            raise ValueError(f"duplicate query name {query.name!r}: {previous} and {path}")
+        names[query.name] = path
+    return loaded
+
+
+def python_annotation(annotation: str) -> str:
+    if annotation.endswith("?"):
+        return f"{annotation[:-1]} | None"
+    return annotation
+
+
+def _validate_identifier(name: str, source: str, line: int, kind: str) -> None:
+    if keyword.iskeyword(name):
+        raise QueryParseError(source, line, f"{kind} name {name!r} is a Python keyword")
+    if kind == "parameter" and name == "db":
+        raise QueryParseError(
+            source, line, "parameter name 'db' is reserved by generated functions"
+        )
+
+
+def _validate_annotation(annotation: str, source: str, line: int) -> None:
+    base = annotation.removesuffix("?")
+    if base not in _ALLOWED_TYPES:
+        allowed = ", ".join(sorted(_ALLOWED_TYPES))
+        raise QueryParseError(source, line, f"unsupported type {base!r}; choose one of {allowed}")

hayate_sql/py.typed

@@ -0,0 +1 @@
+