sqlacache 0.1.0__py3-none-any.whl

sqlacache/__init__.py

@@ -0,0 +1,14 @@
+"""Public package exports for sqlacache."""
+
+from sqlacache.config import configure
+from sqlacache.exceptions import ConfigError
+from sqlacache.manager import CacheManager
+
+__all__ = [
+    "CacheManager",
+    "ConfigError",
+    "__version__",
+    "configure",
+]
+
+__version__ = "0.1.0"

sqlacache/config.py

@@ -0,0 +1,175 @@
+"""Configuration helpers for sqlacache."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from importlib import import_module
+from typing import Any
+from urllib.parse import urlparse
+
+from sqlacache.exceptions import ConfigError
+from sqlacache.manager import CacheManager
+
+ALL_OPS = frozenset({"get", "fetch", "count", "exists"})
+VALID_OPS = ALL_OPS
+
+
+def normalize_ops(ops_config: str | Iterable[str] | None) -> frozenset[str]:
+    """Normalize an ops config into a validated frozenset."""
+
+    if ops_config is None:
+        return frozenset()
+    if ops_config == "all":
+        return ALL_OPS
+    if isinstance(ops_config, str):
+        raise ConfigError(f"Unknown ops value: {ops_config!r}")
+
+    normalized = frozenset(ops_config)
+    invalid_ops = normalized - VALID_OPS
+    if invalid_ops:
+        raise ConfigError(f"Unknown ops: {sorted(invalid_ops)!r}")
+    return normalized
+
+
+def _resolve_model(model_path: str) -> type[Any]:
+    """Resolve a dotted import path to a Python class."""
+
+    module_path, separator, class_name = model_path.rpartition(".")
+    if not separator or not module_path or not class_name:
+        raise ConfigError(f"Invalid model path: {model_path!r}")
+
+    try:
+        module = import_module(module_path)
+    except ImportError as exc:  # pragma: no cover - exact import failures vary
+        raise ConfigError(f"Could not import model module {module_path!r}") from exc
+
+    try:
+        model = getattr(module, class_name)
+    except AttributeError as exc:  # pragma: no cover - exact import failures vary
+        raise ConfigError(f"Module {module_path!r} does not define {class_name!r}") from exc
+
+    if not isinstance(model, type):
+        raise ConfigError(f"Resolved model path {model_path!r} is not a class")
+    return model
+
+
+def _normalize_backend(
+    backend: str | Mapping[str, Any],
+    *,
+    serializer: str,
+    prefix: str,
+    compress: str | None,
+) -> dict[str, Any]:
+    if isinstance(backend, str):
+        parsed = urlparse(backend)
+        if not parsed.scheme:
+            raise ConfigError(f"Invalid backend URL: {backend!r}")
+        normalized_backend: dict[str, Any] = {"url": backend}
+    elif isinstance(backend, Mapping):
+        url = backend.get("url")
+        if not isinstance(url, str) or not url:
+            raise ConfigError("Backend mapping must define a non-empty 'url' string")
+        parsed = urlparse(url)
+        if not parsed.scheme:
+            raise ConfigError(f"Invalid backend URL: {url!r}")
+        normalized_backend = dict(backend)
+    else:
+        raise ConfigError("Backend must be a URL string or mapping")
+
+    normalized_backend.setdefault("pickle_type", serializer)
+    if compress is not None:
+        normalized_backend.setdefault("compress_type", compress)
+    return normalized_backend
+
+
+def _normalize_models(
+    models: Mapping[str, Mapping[str, Any] | None],
+    *,
+    default_timeout: int,
+) -> tuple[dict[str, dict[str, Any] | None], dict[str, Any] | None]:
+    if not models:
+        raise ConfigError("models configuration must not be empty")
+
+    wildcard_raw = models.get("*")
+    wildcard_config: dict[str, Any] | None = None
+    if wildcard_raw is not None:
+        if not isinstance(wildcard_raw, Mapping):
+            raise ConfigError("Wildcard model config must be a mapping or None")
+        wildcard_timeout = wildcard_raw.get("timeout", default_timeout)
+        if not isinstance(wildcard_timeout, int) or wildcard_timeout <= 0:
+            raise ConfigError("Wildcard timeout must be a positive integer")
+        wildcard_config = {
+            "ops": normalize_ops(wildcard_raw.get("ops", "all")),
+            "timeout": wildcard_timeout,
+        }
+
+    normalized_models: dict[str, dict[str, Any] | None] = {}
+    for model_path, raw_config in models.items():
+        if not isinstance(model_path, str) or not model_path:
+            raise ConfigError("Model keys must be non-empty strings")
+
+        if model_path != "*" and "." not in model_path:
+            raise ConfigError(f"Invalid model path: {model_path!r}")
+
+        if raw_config is None:
+            normalized_models[model_path] = None
+            continue
+
+        if not isinstance(raw_config, Mapping):
+            raise ConfigError(f"Model config for {model_path!r} must be a mapping or None")
+
+        timeout = raw_config.get("timeout")
+        if timeout is None:
+            timeout = wildcard_config["timeout"] if wildcard_config is not None else default_timeout
+        if not isinstance(timeout, int) or timeout <= 0:
+            raise ConfigError(f"Timeout for {model_path!r} must be a positive integer")
+
+        ops_default = wildcard_config["ops"] if wildcard_config is not None else "all"
+        normalized_models[model_path] = {
+            "ops": normalize_ops(raw_config.get("ops", ops_default)),
+            "timeout": timeout,
+        }
+
+    return normalized_models, wildcard_config
+
+
+def configure(
+    *,
+    backend: str | Mapping[str, Any],
+    models: Mapping[str, Mapping[str, Any] | None],
+    serializer: str = "sqlalchemy",
+    invalidation: str = "row",
+    prefix: str = "sqlacache",
+    default_timeout: int = 3600,
+    compress: str | None = None,
+) -> CacheManager:
+    """Create a cache manager from validated configuration."""
+
+    if invalidation not in {"row", "table"}:
+        raise ConfigError(f"Unsupported invalidation mode: {invalidation!r}")
+    if not isinstance(default_timeout, int) or default_timeout <= 0:
+        raise ConfigError("default_timeout must be a positive integer")
+
+    normalized_backend = _normalize_backend(
+        backend,
+        serializer=serializer,
+        prefix=prefix,
+        compress=compress,
+    )
+    normalized_models, wildcard_config = _normalize_models(
+        models,
+        default_timeout=default_timeout,
+    )
+
+    return CacheManager(
+        config={
+            "backend": normalized_backend,
+            "models": normalized_models,
+            "wildcard": wildcard_config,
+            "serializer": serializer,
+            "invalidation": invalidation,
+            "prefix": prefix,
+            "default_timeout": default_timeout,
+            "compress": compress,
+        }
+    )

sqlacache/contrib/__init__.py

@@ -0,0 +1 @@
+"""Framework integration stubs."""

sqlacache/contrib/fastapi.py

@@ -0,0 +1 @@
+"""FastAPI integration placeholder."""

sqlacache/contrib/prometheus.py

@@ -0,0 +1 @@
+"""Prometheus integration placeholder."""

sqlacache/exceptions.py

@@ -0,0 +1,13 @@
+"""Exception hierarchy for sqlacache."""
+
+
+class CacheError(Exception):
+    """Base exception for sqlacache."""
+
+
+class ConfigError(CacheError):
+    """Raised for invalid cache configuration."""
+
+
+class TransportError(CacheError):
+    """Raised for cache transport failures."""

sqlacache/interceptor.py

@@ -0,0 +1,128 @@
+"""SQLAlchemy ORM interception hooks."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, cast
+
+from sqlalchemy.orm import ORMExecuteState, loading
+from sqlalchemy.util import await_only
+
+from sqlacache.invalidation import _bump_table_version, generate_tags
+from sqlacache.utils.query_analysis import (
+    detect_operation_type,
+    extract_pks_from_fetch_result,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def merge_cached_result(session: Any, statement: Any, frozen: Any) -> Any:
+    """Merge a frozen result back into a sync or async SQLAlchemy session."""
+
+    target_session = getattr(session, "sync_session", session)
+    merged = cast("Any", loading.merge_frozen_result(target_session, statement, frozen, load=False))  # type: ignore[no-untyped-call]
+    return merged()
+
+
+async def cache_query_result(
+    manager: Any,
+    statement: Any,
+    result: Any,
+    models: list[type[Any]],
+    timeout: int,
+) -> Any:
+    """Freeze and cache a SQLAlchemy result object with dependency tags."""
+
+    frozen = result.freeze()
+    pks_by_model = extract_pks_from_fetch_result(list(frozen.data), models)
+    tags: list[str] = []
+    for model, pks in pks_by_model.items():
+        tags.extend(generate_tags(model, pks))
+
+    key = await manager._build_cache_key(statement, models)
+    await manager._transport.set(key, frozen, expire=timeout, tags=tags)
+    return merge_cached_result(result.session, statement, frozen)
+
+
+def build_do_orm_execute_handler(manager: Any) -> Any:
+    """Build the Session.do_orm_execute event handler for a manager instance."""
+
+    def handler(execute_state: ORMExecuteState) -> Any:
+        if not manager._matches_session(execute_state.session):
+            return execute_state.invoke_statement()
+        if execute_state.execution_options.get("sqlacache_skip_interceptor"):
+            return execute_state.invoke_statement()
+
+        if execute_state.is_select:
+            if getattr(execute_state.session, "_is_asyncio", False):
+                return await_only(resolve_cached_result(manager, execute_state))
+            return execute_state.invoke_statement()
+        if execute_state.is_update or execute_state.is_delete:
+            if getattr(execute_state.session, "_is_asyncio", False):
+                return await_only(handle_bulk_mutation(manager, execute_state))
+            return execute_state.invoke_statement()
+        return execute_state.invoke_statement()
+
+    return handler
+
+
+def build_invalidation_handler(manager: Any, action: str) -> Any:
+    """Build a mapper event handler that invalidates on row mutation."""
+
+    def handler(mapper: Any, connection: Any, target: Any) -> None:
+        del connection
+        manager._schedule_invalidation(mapper.class_, target, action=action)
+
+    return handler
+
+
+def build_bulk_update_handler(manager: Any) -> Any:
+    def handler(update_context: Any) -> None:
+        mapper = getattr(update_context, "mapper", None)
+        if mapper is not None:
+            manager._schedule_table_bump(mapper.class_)
+
+    return handler
+
+
+def build_bulk_delete_handler(manager: Any) -> Any:
+    def handler(delete_context: Any) -> None:
+        mapper = getattr(delete_context, "mapper", None)
+        if mapper is not None:
+            manager._schedule_table_bump(mapper.class_)
+
+    return handler
+
+
+async def resolve_cached_result(manager: Any, execute_state: ORMExecuteState) -> Any:
+    statement = execute_state.statement
+    models = manager._extract_models(statement)
+    if not models:
+        return execute_state.invoke_statement()
+
+    op = detect_operation_type(statement, models)
+    primary_model = models[0]
+    if not manager.is_enabled(primary_model, op):
+        return execute_state.invoke_statement()
+
+    key = await manager._build_cache_key(statement, models)
+    cached = await manager._transport.get(key)
+    if cached is not None:
+        return merge_cached_result(execute_state.session, statement, cached)
+
+    result = execute_state.invoke_statement()
+    model_config = manager.get_model_config(primary_model)
+    timeout = model_config["timeout"] if model_config else manager.config["default_timeout"]
+    return await cache_query_result(manager, statement, result, models, timeout)
+
+
+async def handle_bulk_mutation(manager: Any, execute_state: ORMExecuteState) -> Any:
+    statement = execute_state.statement
+    result = execute_state.invoke_statement()
+    models = manager._extract_models(statement)
+    transport = manager._transport
+    if transport is not None:
+        for model in models:
+            await _bump_table_version(transport, model)
+    return result

sqlacache/invalidation.py

@@ -0,0 +1,45 @@
+"""Row-level invalidation helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from sqlacache.transport import CacheTransport
+
+_TABLE_VERSION_PREFIX = "__sqlacache_tv__"
+
+
+def generate_tags(model: type[Any], pks: list[Any]) -> list[str]:
+    """Generate dependency tags from model/table and PK values."""
+
+    table_name = model.__tablename__
+    return [f"{table_name}:{pk}" for pk in pks if pk is not None]
+
+
+async def invalidate_tags(transport: CacheTransport, *tags: str) -> None:
+    """Invalidate transport entries for the provided tags."""
+
+    if not tags:
+        return
+    await transport.delete_tags(*tags)
+
+
+def _table_version_key(model: type[Any] | str) -> str:
+    table_name = model if isinstance(model, str) else model.__tablename__
+    return f"{_TABLE_VERSION_PREFIX}{table_name}"
+
+
+async def _bump_table_version(transport: CacheTransport, model: type[Any] | str) -> int:
+    """Increment the table-version counter in the shared cache and return the new value."""
+
+    key = _table_version_key(model)
+    return await transport.incr(key)
+
+
+async def _get_table_version(transport: CacheTransport, model: type[Any] | str) -> int:
+    """Return the current table-version counter from the shared cache."""
+
+    key = _table_version_key(model)
+    value = await transport.get(key)
+    return int(value) if value is not None else 0