python-mapper 0.3.0__py3-none-any.whl

python_mapper/observability.py

@@ -0,0 +1,117 @@
+"""Structured, parameter-safe SQL execution logging."""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import time
+from typing import Any
+
+from python_mapper.plugins import StatementContext, StatementExecutor, StatementResult
+
+
+def _normalized_sql(sql: str) -> str:
+    return " ".join(sql.split())
+
+
+def _fingerprint(sql: str) -> str:
+    return hashlib.sha256(_normalized_sql(sql).encode("utf-8")).hexdigest()[:16]
+
+
+class SqlLoggingPlugin:
+    """Observe final SQL shape without logging parameter values by default."""
+
+    def __init__(
+        self,
+        *,
+        slow_query_threshold_ms: float = 500.0,
+        logger_name: str = "python_mapper.query",
+        include_sql: bool = True,
+    ) -> None:
+        if slow_query_threshold_ms < 0:
+            raise ValueError("slow_query_threshold_ms must be non-negative")
+        self.slow_query_threshold_ms = slow_query_threshold_ms
+        self.logger = logging.getLogger(logger_name)
+        self.include_sql = include_sql
+
+    def _event(
+        self,
+        context: StatementContext,
+        *,
+        duration_ms: float,
+        row_count: int | None,
+        slow: bool,
+        error_type: str | None = None,
+    ) -> dict[str, Any]:
+        sql = context.compiled_sql or context.sql
+        event: dict[str, Any] = {
+            "event": "pymapper.query",
+            "statement_id": context.statement_id,
+            "operation": context.operation,
+            "parent_statement_id": context.parent_statement_id,
+            "sql_fingerprint": _fingerprint(sql),
+            "duration_ms": round(duration_ms, 3),
+            "connection_wait_ms": round(context.connection_wait_ms, 3),
+            "row_count": row_count,
+            "parameter_names": sorted(context.parameters),
+            "parameter_types": [
+                type(context.parameters[name]).__name__
+                for name in sorted(context.parameters)
+            ],
+            "slow": slow,
+            "error_type": error_type,
+        }
+        if self.include_sql:
+            event["sql"] = _normalized_sql(sql)
+        return event
+
+    async def execute(
+        self,
+        context: StatementContext,
+        call_next: StatementExecutor,
+    ) -> StatementResult:
+        started_at = time.perf_counter()
+        try:
+            result = await call_next(context)
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:
+            duration_ms = (time.perf_counter() - started_at) * 1000
+            event = self._event(
+                context,
+                duration_ms=duration_ms,
+                row_count=None,
+                slow=duration_ms >= self.slow_query_threshold_ms,
+                error_type=type(error).__name__,
+            )
+            self.logger.exception(
+                "pymapper query failed statement_id=%s fingerprint=%s duration_ms=%.3f",
+                context.statement_id,
+                event["sql_fingerprint"],
+                duration_ms,
+                extra={"pymapper": event},
+            )
+            raise
+
+        duration_ms = (time.perf_counter() - started_at) * 1000
+        slow = duration_ms >= self.slow_query_threshold_ms
+        event = self._event(
+            context,
+            duration_ms=duration_ms,
+            row_count=result.rowcount,
+            slow=slow,
+        )
+        level = logging.WARNING if slow else logging.DEBUG
+        self.logger.log(
+            level,
+            "pymapper query statement_id=%s fingerprint=%s duration_ms=%.3f rows=%d",
+            context.statement_id,
+            event["sql_fingerprint"],
+            duration_ms,
+            result.rowcount,
+            extra={"pymapper": event},
+        )
+        return result
+
+
+__all__ = ["SqlLoggingPlugin"]

python_mapper/pagination.py

@@ -0,0 +1,224 @@
+"""Opt-in pagination models and statement plugin."""
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from python_mapper.compiler import (
+    contains_top_level_keyword,
+    contains_top_level_sequence,
+)
+from python_mapper.errors import PaginationConflictError, PaginationError
+from python_mapper.plugins import StatementContext, StatementExecutor, StatementResult
+
+DEFAULT_PAGE_SIZE = 30
+MAX_PAGE_SIZE = 200
+PAGE_MARKER = "/*__PYTHON_MAPPER_PAGE__*/"
+PAGE_LIMIT_PARAMETER = "__page_size"
+PAGE_OFFSET_PARAMETER = "__page_offset"
+
+
+@dataclass(frozen=True, slots=True)
+class PaginationOptions:
+    """Per-call pagination switch; disabled calls must remain raw mapper calls."""
+
+    enabled: bool = False
+    page_number: int = 1
+    page_size: int = DEFAULT_PAGE_SIZE
+    include_total: bool = True
+
+    def normalized(self) -> PaginationOptions:
+        if self.page_number < 1:
+            raise PaginationError("page_number must be greater than or equal to 1")
+        if self.page_size < 1 or self.page_size > MAX_PAGE_SIZE:
+            raise PaginationError(
+                f"page_size must be between 1 and {MAX_PAGE_SIZE}"
+            )
+        return PaginationOptions(
+            enabled=self.enabled,
+            page_number=self.page_number,
+            page_size=self.page_size,
+            include_total=self.include_total,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PageMetadata:
+    page_number: int
+    page_size: int
+    total: int | None
+    total_pages: int | None
+    has_next: bool
+
+
+@dataclass(slots=True)
+class Page[ItemValue]:
+    """Framework-neutral page returned directly by a ``Page[T]`` mapper."""
+
+    items: list[ItemValue] = field(default_factory=list)
+    total: int = 0
+    page: int = 1
+    page_size: int = DEFAULT_PAGE_SIZE
+    pages: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class QueryResult[ItemValue]:
+    """Stable result from the optional ``query`` facade."""
+
+    items: list[ItemValue]
+    pagination: PageMetadata | None = None
+
+    def map[MappedValue](
+        self,
+        converter: Callable[[ItemValue], MappedValue],
+    ) -> QueryResult[MappedValue]:
+        return QueryResult(
+            items=[converter(item) for item in self.items],
+            pagination=self.pagination,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PaginationSpec:
+    statement_id: str
+    count_statement_id: str | None = None
+    marker_count: int = 0
+
+
+def _scalar_count(result: StatementResult, statement_id: str) -> int:
+    if not result.rows:
+        raise PaginationError(
+            f"pagination count statement '{statement_id}' returned no rows"
+        )
+    row = result.rows[0]
+    values = list(dict(row).values())
+    if len(values) != 1:
+        raise PaginationError(
+            f"pagination count statement '{statement_id}' must return exactly one column"
+        )
+    try:
+        return int(values[0])
+    except (TypeError, ValueError) as error:
+        raise PaginationError(
+            f"pagination count statement '{statement_id}' returned a non-integer value"
+        ) from error
+
+
+def _append_page_clause(sql: str, clause: str) -> str:
+    stripped = sql.rstrip()
+    if stripped.endswith(";"):
+        return f"{stripped[:-1].rstrip()}\n{clause};"
+    return f"{stripped}\n{clause}"
+
+
+class PaginationPlugin:
+    """Add LIMIT/OFFSET only for one explicitly enabled query invocation."""
+
+    def __init__(self, options: PaginationOptions, spec: PaginationSpec) -> None:
+        self.options = options.normalized()
+        self.spec = spec
+
+    async def execute(
+        self,
+        context: StatementContext,
+        call_next: StatementExecutor,
+    ) -> StatementResult:
+        if not self.options.enabled:
+            return await call_next(context)
+        if context.statement_kind != "select":
+            raise PaginationError(
+                f"pagination only supports <select>: {context.statement_id}"
+            )
+
+        sql = context.sql
+        marker_count = sql.count(PAGE_MARKER)
+        has_manual_page = any(
+            contains_top_level_keyword(sql, keyword)
+            for keyword in ("LIMIT", "OFFSET", "FETCH")
+        )
+        if marker_count and has_manual_page:
+            raise PaginationConflictError(
+                f"mapper '{context.statement_id}' contains both <page/> and top-level "
+                "LIMIT/OFFSET/FETCH"
+            )
+        if marker_count > 1:
+            raise PaginationConflictError(
+                f"mapper '{context.statement_id}' contains more than one <page/> marker"
+            )
+        if has_manual_page:
+            raise PaginationConflictError(
+                f"mapper '{context.statement_id}' already contains top-level "
+                "LIMIT/OFFSET/FETCH; disable pagination or remove the manual clause"
+            )
+        if not contains_top_level_sequence(sql, "ORDER", "BY"):
+            raise PaginationError(
+                f"pagination statement '{context.statement_id}' requires a top-level ORDER BY"
+            )
+        if marker_count == 0 and contains_top_level_sequence(sql, "FOR", "UPDATE"):
+            raise PaginationError(
+                f"pagination statement '{context.statement_id}' uses FOR UPDATE; "
+                "add <page/> to declare the clause position"
+            )
+
+        total: int | None = None
+        if self.options.include_total:
+            count_statement_id = self.spec.count_statement_id
+            if count_statement_id is None:
+                raise PaginationError(
+                    f"pagination statement '{context.statement_id}' requires countRef "
+                    "when include_total=True"
+                )
+            count_result = await context.execute_related(
+                count_statement_id,
+                context.input_parameters,
+                "pagination.count",
+                context.statement_id,
+            )
+            total = _scalar_count(count_result, count_statement_id)
+
+        page_size = self.options.page_size
+        offset = (self.options.page_number - 1) * page_size
+        query_limit = page_size if total is not None else page_size + 1
+        clause = f"LIMIT :{PAGE_LIMIT_PARAMETER} OFFSET :{PAGE_OFFSET_PARAMETER}"
+        context.sql = (
+            sql.replace(PAGE_MARKER, clause)
+            if marker_count
+            else _append_page_clause(sql, clause)
+        )
+        context.parameters[PAGE_LIMIT_PARAMETER] = query_limit
+        context.parameters[PAGE_OFFSET_PARAMETER] = offset
+        result = await call_next(context)
+
+        rows = list(result.rows or [])
+        if total is None:
+            has_next = len(rows) > page_size
+            rows = rows[:page_size]
+            result = StatementResult(rows=rows, rowcount=len(rows))
+            total_pages = None
+        else:
+            has_next = offset + len(rows) < total
+            total_pages = math.ceil(total / page_size) if total else 0
+
+        context.attributes["pagination"] = PageMetadata(
+            page_number=self.options.page_number,
+            page_size=page_size,
+            total=total,
+            total_pages=total_pages,
+            has_next=has_next,
+        )
+        return result
+
+
+__all__ = [
+    "DEFAULT_PAGE_SIZE",
+    "MAX_PAGE_SIZE",
+    "PAGE_MARKER",
+    "Page",
+    "PageMetadata",
+    "PaginationOptions",
+    "PaginationPlugin",
+    "PaginationSpec",
+    "QueryResult",
+]

python_mapper/plugins.py

@@ -0,0 +1,94 @@
+"""Framework-neutral statement execution plugin contracts."""
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from python_mapper.database import ConnectionLike
+
+
+@dataclass(slots=True)
+class StatementResult:
+    """Raw database result before resultType/resultMap materialization."""
+
+    rows: list[Any] | None
+    rowcount: int
+
+    @property
+    def returns_rows(self) -> bool:
+        return self.rows is not None
+
+
+RelatedStatementExecutor = Callable[
+    [str, Mapping[str, Any], str, str | None],
+    Awaitable[StatementResult],
+]
+
+
+@dataclass(slots=True)
+class StatementContext:
+    """Mutable execution state shared by one statement plugin chain."""
+
+    statement_id: str
+    statement_kind: str | None
+    sql: str
+    input_parameters: dict[str, Any]
+    parameters: dict[str, Any]
+    connection: ConnectionLike
+    execute_related: RelatedStatementExecutor
+    operation: str = "query"
+    parent_statement_id: str | None = None
+    connection_wait_ms: float = 0.0
+    compiled_sql: str | None = None
+    compiled_args: tuple[Any, ...] = ()
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+
+StatementExecutor = Callable[[StatementContext], Awaitable[StatementResult]]
+
+
+class StatementPlugin(Protocol):
+    """Around-execution extension point.
+
+    Plugin instances are process-level configuration and may serve concurrent
+    statements. Implementations should therefore remain stateless or protect
+    their own mutable state, and must call ``call_next`` exactly once unless they
+    intentionally short-circuit execution.
+    """
+
+    async def execute(
+        self,
+        context: StatementContext,
+        call_next: StatementExecutor,
+    ) -> StatementResult: ...
+
+
+async def run_plugin_chain(
+    context: StatementContext,
+    plugins: Sequence[StatementPlugin],
+    terminal: StatementExecutor,
+) -> StatementResult:
+    """Run a reusable, non-destructive interceptor chain."""
+
+    async def invoke(index: int, current: StatementContext) -> StatementResult:
+        if index >= len(plugins):
+            return await terminal(current)
+        plugin = plugins[index]
+
+        async def call_next(next_context: StatementContext) -> StatementResult:
+            return await invoke(index + 1, next_context)
+
+        return await plugin.execute(current, call_next)
+
+    return await invoke(0, context)
+
+
+__all__ = [
+    "RelatedStatementExecutor",
+    "StatementContext",
+    "StatementExecutor",
+    "StatementPlugin",
+    "StatementResult",
+    "run_plugin_chain",
+]