patera-caching 0.1.0__tar.gz

patera_caching-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.3
+Name: patera-caching
+Version: 0.1.0
+Requires-Dist: cachetools>=7.0.5
+Requires-Dist: patera
+Requires-Dist: redis>=5.0 ; extra == 'all'
+Requires-Dist: aiosqlite>=0.20 ; extra == 'all'
+Requires-Dist: redis>=5.0 ; extra == 'redis'
+Requires-Dist: aiosqlite>=0.20 ; extra == 'sqlite'
+Requires-Python: >=3.12
+Provides-Extra: all
+Provides-Extra: redis
+Provides-Extra: sqlite

patera_caching-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "patera-caching"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+  "cachetools>=7.0.5",
+  "patera",
+]
+
+[project.optional-dependencies]
+redis = [
+  "redis>=5.0",
+]
+sqlite = [
+  "aiosqlite>=0.20",
+]
+all = [
+  "redis>=5.0",
+  "aiosqlite>=0.20",
+]
+
+[tool.uv.sources]
+patera = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "patera.caching"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"

patera_caching-0.1.0/src/patera/caching/__init__.py

@@ -0,0 +1,8 @@
+"""
+Caching module
+"""
+
+from .cache import Cache, CacheConfig
+from .backends.base_cache_backend import BaseCacheBackend
+
+__all__ = ["Cache", "BaseCacheBackend", "CacheConfig"]

patera_caching-0.1.0/src/patera/caching/backends/base_cache_backend.py

@@ -0,0 +1,51 @@
+"""
+Base/Blueprint class for cache implementation
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from patera import Patera
+
+
+class BaseCacheBackend(ABC):
+    """
+    Abstract cache backend blueprint.
+
+    Subclasses should implement:
+    - configure_from_app(cls, app) -> BaseCacheBackend
+    - connect / disconnect
+    - get / set / delete / clear
+    """
+
+    @classmethod
+    @abstractmethod
+    def configure_from_app(
+        cls, app: "Patera", configs: dict[str, Any]
+    ) -> "BaseCacheBackend":
+        """Create a configured backend instance using app config."""
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish any required connections (no-op for memory)."""
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Tear down connections (no-op for memory)."""
+
+    @abstractmethod
+    async def get(self, key: str) -> Optional[dict]:
+        """Return cached payload dict or None."""
+
+    @abstractmethod
+    async def set(self, key: str, value: dict, duration: Optional[int] = None) -> None:
+        """Store payload dict under key with optional TTL in seconds."""
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Delete a cached entry if present."""
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear the entire cache namespace."""

patera_caching-0.1.0/src/patera/caching/backends/memory_cache_backend.py

@@ -0,0 +1,72 @@
+"""
+In-memory cache implementation
+"""
+
+from typing import Optional, cast, TYPE_CHECKING, Any
+import asyncio
+
+from cachetools import TTLCache
+
+from .base_cache_backend import BaseCacheBackend
+
+if TYPE_CHECKING:
+    from patera import Patera
+
+
+class MemoryCacheBackend(BaseCacheBackend):
+    """
+    In-memory cache using cachetools.TTLCache for bounded size and base TTL.
+
+
+    Per-item TTL by storing an explicit expire timestamp alongside
+    the payload; TTLCache provides a global upper bound and eviction.
+    """
+
+    def __init__(self, default_ttl: int = 300, maxsize: int = 10_000):
+        self.default_ttl = int(default_ttl)
+        # Stores: key -> {payload: dict, expire: float}
+        self._cache: TTLCache[str, dict] = TTLCache(
+            maxsize=maxsize, ttl=self.default_ttl
+        )
+
+    # ---- config ----
+    @classmethod
+    def configure_from_app(
+        cls, app: "Patera", configs: dict[str, Any]
+    ) -> "MemoryCacheBackend":
+        default_ttl = configs["DURATION"]
+        maxsize = configs.get("MEMORY_MAXSIZE", 10_000)
+        return cls(default_ttl=default_ttl, maxsize=maxsize)
+
+    async def connect(self) -> None:  # pragma: no cover - nothing to do
+        return None
+
+    async def disconnect(self) -> None:
+        self._cache.clear()
+
+    async def get(self, key: str) -> Optional[dict]:
+        item = self._cache.get(key)
+        if not item:
+            return None
+        expire = item.get("expire", 0)
+        if expire < asyncio.get_event_loop().time():
+            try:
+                del self._cache[key]
+            except KeyError:
+                pass
+            return None
+        return cast(dict, item.get("payload"))
+
+    async def set(self, key: str, value: dict, duration: Optional[int] = None) -> None:
+        ttl = int(duration) if duration is not None else self.default_ttl
+        expire = asyncio.get_event_loop().time() + ttl
+        self._cache[key] = {"payload": value, "expire": expire}
+
+    async def delete(self, key: str) -> None:
+        try:
+            del self._cache[key]
+        except KeyError:
+            pass
+
+    async def clear(self) -> None:
+        self._cache.clear()

patera_caching-0.1.0/src/patera/caching/backends/redis_cache_backend.py

@@ -0,0 +1,111 @@
+"""
+Redis cache implementation
+
+CACHE_REDIS_URL       = "redis://localhost:6379/0"   # required
+CACHE_REDIS_PASSWORD  = None                          # optional
+CACHE_DURATION        = 300                           # optional (default TTL)
+CACHE_KEY_PREFIX      = "patera:cache:"              # optional prefix/namespace
+"""
+
+from __future__ import annotations
+
+import pickle
+from typing import Optional, cast, List, TYPE_CHECKING, Any
+
+from redis.asyncio import Redis, from_url
+
+from .base_cache_backend import BaseCacheBackend
+
+if TYPE_CHECKING:
+    from patera import Patera
+
+
+class RedisCacheBackend(BaseCacheBackend):
+    """Redis-backed cache using binary pickled payloads."""
+
+    def __init__(
+        self,
+        url: str,
+        password: Optional[str] = None,
+        default_ttl: int = 300,
+        key_prefix: str = "",
+    ) -> None:
+        if not url:
+            raise ValueError("CACHE_REDIS_URL must be set for RedisCacheBackend")
+        self._url = url
+        self._password = password
+        self._client: Optional[Redis] = None
+        self.default_ttl = int(default_ttl)
+        # Normalize prefix to empty or end with ':' for nicer namespaces
+        if key_prefix and not key_prefix.endswith(":") and key_prefix != "":
+            key_prefix = key_prefix + ":"
+        self._prefix = key_prefix
+
+    @classmethod
+    def configure_from_app(
+        cls, app: Patera, configs: dict[str, Any]
+    ) -> "RedisCacheBackend":
+        url = configs.get("REDIS_URL", "")
+        password = configs.get("REDIS_PASSWORD", None)
+        ttl = cast(int, configs.get("DURATION"))
+        key_prefix = configs.get("KEY_PREFIX", "")
+        return cls(url=url, password=password, default_ttl=ttl, key_prefix=key_prefix)
+
+    async def connect(self) -> None:
+        if not self._client:
+            # decode_responses=False -> bytes in/out, good for pickled values
+            self._client = await from_url(
+                self._url,
+                encoding="utf-8",
+                decode_responses=False,
+                password=self._password,
+            )
+
+    async def disconnect(self) -> None:
+        if self._client:
+            await self._client.close()
+            self._client = None
+
+    # ---- helpers ----
+    def _k(self, key: str) -> str:
+        return f"{self._prefix}{key}" if self._prefix else key
+
+    async def _ensure(self) -> Redis:
+        if not self._client:
+            # Allow lazy connect if caller forgot to call connect()
+            await self.connect()
+        assert self._client is not None
+        return self._client
+
+    async def get(self, key: str) -> Optional[dict]:
+        client = await self._ensure()
+        raw = await client.get(self._k(key))
+        if not raw:
+            return None
+        return cast(dict, pickle.loads(raw))
+
+    async def set(self, key: str, value: dict, duration: Optional[int] = None) -> None:
+        client = await self._ensure()
+        ttl = int(duration) if duration is not None else self.default_ttl
+        await client.setex(self._k(key), ttl, pickle.dumps(value))
+
+    async def delete(self, key: str) -> None:
+        client = await self._ensure()
+        await client.delete(self._k(key))
+
+    async def clear(self) -> None:
+        client = await self._ensure()
+        if self._prefix and self._prefix != "":
+            keys: List[bytes] = []
+            async for k in client.scan_iter(match=f"{self._prefix}*"):
+                keys.append(k)
+            if keys:
+                # Pipeline deletion in chunks to avoid huge payloads
+                # pylint: disable-next=C0103
+                CHUNK = 1000
+                for i in range(0, len(keys), CHUNK):
+                    chunk = keys[i : i + CHUNK]
+                    await client.delete(*chunk)
+        else:
+            # flushes entire Redis db in case no namespace prefix is configured
+            await client.flushdb()

patera_caching-0.1.0/src/patera/caching/backends/sqlite_cache_backend.py

@@ -0,0 +1,239 @@
+"""
+SQLite cache backend
+
+Indicated values are defaults
+CACHE_SQLITE_PATH: str = "./pyjolt_cache.sqlite3" # file path (required for persistence)
+CACHE_SQLITE_TABLE: str = "cache_entries" # table name
+CACHE_KEY_PREFIX: str = "patera:cache:" # optional key namespace
+CACHE_DURATION: int = 300 # default TTL seconds
+CACHE_SQLITE_WAL_CHECKPOINT_MODE: str = "PASSIVE" #PASSIVE|FULL|RESTART|TRUNCATE
+CACHE_SQLITE_WAL_CHECKPOINT_EVERY: int = 100 #run checkpoint every N write ops
+"""
+
+from __future__ import annotations
+
+import os
+import pickle
+import time
+from typing import Optional, TYPE_CHECKING, Tuple, cast, Any
+from pydantic import BaseModel, Field
+
+import aiosqlite
+
+from .base_cache_backend import BaseCacheBackend
+
+if TYPE_CHECKING:
+    from patera import Patera
+
+
+class SQLiteCacheConfig(BaseModel):
+    CACHE_SQLITE_PATH: str = Field(
+        "./pyjolt_cache.db",
+        description="SQLite DB file path (use ':memory:' for in-memory)",
+    )
+    CACHE_SQLITE_TABLE: str = Field(
+        "cache_entries", description="Table name for cache entries"
+    )
+    CACHE_DURATION: int = Field(300, description="Cache default TTL in seconds")
+    CACHE_KEY_PREFIX: str = Field("", description="Cache key prefix/namespace")
+    CACHE_SQLITE_WAL_CHECKPOINT_MODE: str = Field(
+        "PASSIVE",
+        description="Mode for WAL checkpointing: PASSIVE|FULL|RESTART|TRUNCATE",
+    )
+    CACHE_SQLITE_WAL_CHECKPOINT_EVERY: int = Field(
+        100, description="Insert WAL checkpoint every N write operations"
+    )
+
+
+class SQLiteCacheBackend(BaseCacheBackend):
+    """SQLite-backed cache using pickled payloads (async via aiosqlite)."""
+
+    def __init__(
+        self,
+        db_path: str,
+        table: str = "cache_entries",
+        default_ttl: int = 300,
+        key_prefix: str = "",
+        checkpoint_mode: str = "PASSIVE",
+        checkpoint_every: int = 100,
+    ) -> None:
+        if not db_path:
+            raise ValueError(
+                "CACHE_SQLITE_PATH must be provided for SQLiteCacheBackend"
+            )
+        self._db_path = db_path
+        self._table = table
+        self.default_ttl = int(default_ttl)
+        self._conn: Optional[aiosqlite.Connection] = None
+        if key_prefix and not key_prefix.endswith(":"):
+            key_prefix = key_prefix + ":"
+        self._prefix = key_prefix
+        # WAL checkpoint settings
+        self._checkpoint_mode = checkpoint_mode.upper()
+        if self._checkpoint_mode not in {"PASSIVE", "FULL", "RESTART", "TRUNCATE"}:
+            raise ValueError(
+                "CACHE_SQLITE_WAL_CHECKPOINT_MODE must be one of PASSIVE|FULL|RESTART|TRUNCATE"
+            )
+        self._checkpoint_every = max(1, int(checkpoint_every))
+        self._write_ops = 0
+
+    @classmethod
+    def configure_from_app(
+        cls, app: "Patera", configs: dict[str, Any]
+    ) -> "SQLiteCacheBackend":
+        db_path = cast(str, configs.get("SQLITE_PATH", "./pyjolt_cache.db"))
+        table = cast(str, configs.get("SQLITE_TABLE", "cache_entries"))
+        default_ttl = int(configs.get("DURATION", 300))
+        key_prefix = cast(str, configs.get("KEY_PREFIX", ""))
+        checkpoint_mode = cast(
+            str, configs.get("SQLITE_WAL_CHECKPOINT_MODE", "PASSIVE")
+        )
+        checkpoint_every = int(configs.get("SQLITE_WAL_CHECKPOINT_EVERY", 100))
+        if db_path != ":memory:":
+            os.makedirs(os.path.dirname(os.path.abspath(db_path)), exist_ok=True)
+        return cls(
+            db_path=db_path,
+            table=table,
+            default_ttl=default_ttl,
+            key_prefix=key_prefix,
+            checkpoint_mode=checkpoint_mode,
+            checkpoint_every=checkpoint_every,
+        )
+
+    async def connect(self) -> None:
+        if self._conn:
+            return
+        self._conn = await aiosqlite.connect(self._db_path)
+        # Pragmas tuned for app caches (good perf/safety tradeoffs)
+        await self._conn.execute("PRAGMA journal_mode=WAL;")
+        await self._conn.execute("PRAGMA synchronous=NORMAL;")
+        await self._conn.execute("PRAGMA foreign_keys=ON;")
+        await self._conn.execute(
+            "PRAGMA busy_timeout=3000;"
+        )  # 3s wait instead of immediate 'database is locked'. Useful for WAL mode with concurrent readers/writers (multiple app workers)
+        await self._conn.execute(
+            "PRAGMA wal_autocheckpoint=1000;"
+        )  # checkpoint every ~1000 pages (~4MB)
+        await self._ensure_schema()
+        await self._conn.commit()
+
+    async def disconnect(self) -> None:
+        if self._conn is None:
+            return
+        await self._conn.close()
+        self._conn = None
+
+    async def _ensure_schema(self) -> None:
+        assert self._conn is not None
+        t = self._table
+        await self._conn.executescript(
+            f"""
+            CREATE TABLE IF NOT EXISTS {t} (
+                k TEXT PRIMARY KEY,
+                v BLOB NOT NULL,
+                expire REAL NOT NULL,
+                updated_at REAL NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_{t}_expire ON {t}(expire);
+            CREATE INDEX IF NOT EXISTS idx_{t}_k_pref ON {t}(k);
+            """
+        )
+
+    def _k(self, key: str) -> str:
+        return f"{self._prefix}{key}" if self._prefix else key
+
+    async def _cleanup_expired(self) -> None:
+        assert self._conn is not None
+        now = time.time()
+        await self._conn.execute(f"DELETE FROM {self._table} WHERE expire <= ?", (now,))
+        await self._conn.commit()
+
+    async def _maybe_checkpoint(self) -> None:
+        """Run WAL checkpoint every N write operations."""
+        assert self._conn is not None
+        self._write_ops += 1
+        if (self._write_ops % self._checkpoint_every) == 0:
+            # PRAGMA wal_checkpoint(PASSIVE)
+            await self._conn.execute(f"PRAGMA wal_checkpoint({self._checkpoint_mode});")
+            await self._conn.commit()
+
+    async def get(self, key: str) -> Optional[dict]:
+        if self._conn is None:
+            await self.connect()
+        assert self._conn is not None
+        k = self._k(key)
+        async with self._conn.execute(
+            f"SELECT v, expire FROM {self._table} WHERE k = ?",
+            (k,),
+        ) as cur:
+            row = await cur.fetchone()
+        if row is None:
+            return None
+        raw, expire = cast(Tuple[bytes, float], row)
+        now = time.time()
+        if expire <= now:
+            await self._conn.execute(f"DELETE FROM {self._table} WHERE k = ?", (k,))
+            await self._conn.commit()
+            # count deletion as a write op for checkpoint cadence
+            await self._maybe_checkpoint()
+            return None
+        try:
+            return cast(dict, pickle.loads(raw))
+        except Exception:
+            # Drop corrupt entry
+            await self._conn.execute(f"DELETE FROM {self._table} WHERE k = ?", (k,))
+            await self._conn.commit()
+            await self._maybe_checkpoint()
+            return None
+
+    async def set(self, key: str, value: dict, duration: Optional[int] = None) -> None:
+        if self._conn is None:
+            await self.connect()
+        assert self._conn is not None
+        ttl = int(duration) if duration is not None else self.default_ttl
+        expire = time.time() + ttl
+        k = self._k(key)
+        raw = pickle.dumps(value)
+        # Upsert with ON CONFLICT
+        await self._conn.execute(
+            f"""
+            INSERT INTO {self._table}(k, v, expire, updated_at)
+            VALUES(?, ?, ?, ?)
+            ON CONFLICT(k) DO UPDATE SET
+                v=excluded.v,
+                expire=excluded.expire,
+                updated_at=excluded.updated_at
+            """,
+            (k, raw, expire, time.time()),
+        )
+        await self._conn.commit()
+        # count insertion as a write op for checkpoint cadence
+        await self._cleanup_expired()
+        await self._maybe_checkpoint()
+
+    async def delete(self, key: str) -> None:
+        if self._conn is None:
+            await self.connect()
+        assert self._conn is not None
+        await self._conn.execute(
+            f"DELETE FROM {self._table} WHERE k = ?", (self._k(key),)
+        )
+        await self._conn.commit()
+        await self._maybe_checkpoint()
+
+    async def clear(self) -> None:
+        if self._conn is None:
+            await self.connect()
+        assert self._conn is not None
+        if self._prefix:
+            like = f"{self._prefix}%"
+            await self._conn.execute(
+                f"DELETE FROM {self._table} WHERE k LIKE ?", (like,)
+            )
+        else:
+            await self._conn.execute(f"DELETE FROM {self._table}")
+        # Checkpoint after full clear to truncate WAL
+        await self._conn.execute(f"PRAGMA wal_checkpoint({self._checkpoint_mode});")
+        await self._conn.commit()
+        # reset write op count after full clear
+        self._write_ops = 0

patera_caching-0.1.0/src/patera/caching/cache.py

@@ -0,0 +1,153 @@
+""" """
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import (
+    Callable,
+    NotRequired,
+    Optional,
+    Type,
+    TypedDict,
+    cast,
+    TYPE_CHECKING,
+    Any,
+)
+from pydantic import BaseModel, Field
+
+from patera.utilities import run_sync_or_async
+from patera.base_extension import BaseExtension
+
+from .backends.base_cache_backend import BaseCacheBackend
+
+if TYPE_CHECKING:
+    from patera import Patera, Response, Request
+
+
+class _CacheConfigs(BaseModel):
+    """Configuration model for Cache extension."""
+
+    BACKEND: Optional[Type[BaseCacheBackend]] = Field(
+        default=None,
+        description="Caching backend class, must be subclass of BaseCacheBackend",
+    )
+    DURATION: Optional[int] = Field(
+        default=300, description="Default cache duration in seconds"
+    )
+
+
+class CacheConfig(TypedDict):
+    """Cache configurations"""
+
+    BACKEND: NotRequired[Type[BaseCacheBackend]]
+    DURATION: NotRequired[int]
+
+
+class Cache(BaseExtension):
+    """
+    Caching system for route handlers with **pluggable backend class**.
+
+    Provide caching implementation as `BACKEND` config. This should be
+    a valid caching implementation of the BaseCacheBackend class.
+    If not provided, defaults to in-memory caching (MemoryCacheBackend).
+
+    Default cache duration is set with `DURATION` config (seconds)
+    """
+
+    def __init__(self, configs_name: Optional[str] = "CACHE"):
+        self._app: "Optional[Patera]" = None
+        self._duration: int = 300
+        self._backend: Optional[BaseCacheBackend] = None
+        self._configs_name = cast(str, configs_name)
+        self._configs: dict[str, Any] = {}
+
+    def init_app(self, app: "Patera") -> None:
+        self._app = app
+        self._configs = app.get_conf(self._configs_name, {})
+        self._configs = self.validate_configs(self._configs, _CacheConfigs)
+
+        self._duration = self._configs["DURATION"]
+        backend_cls = self._configs.get("BACKEND", None)
+        if backend_cls is None:
+            # loads default backend - MemoryCacheBackend
+            # pylint: disable-next=C0415
+            from .backends.memory_cache_backend import MemoryCacheBackend
+
+            backend_cls = MemoryCacheBackend
+        if not issubclass(backend_cls, BaseCacheBackend):
+            raise TypeError(
+                "CACHE_BACKEND must be a class and subclass of BaseCacheBackend"
+            )
+
+        self._backend = cast(Type[BaseCacheBackend], backend_cls).configure_from_app(
+            app, self._configs
+        )
+
+        self._app.add_extension(self)
+        self._app.add_on_startup_method(self.connect)
+        self._app.add_on_shutdown_method(self.disconnect)
+
+    async def connect(self) -> None:
+        if self._backend:
+            await self._backend.connect()
+
+    async def disconnect(self) -> None:
+        if self._backend:
+            await self._backend.disconnect()
+
+    async def set(
+        self, key: str, value: "Response", duration: Optional[int] = None
+    ) -> None:
+        cached_value = {
+            "status_code": value.status_code,
+            "headers": value.headers,
+            "body": value.body,
+        }
+        await cast(BaseCacheBackend, self._backend).set(
+            key, cached_value, duration or self._duration
+        )
+
+    async def get(self, key: str, req: "Request") -> "Optional[Response]":
+        payload = await cast(BaseCacheBackend, self._backend).get(key)
+        if payload is None:
+            return None
+        return await self._make_cached_response(payload, req)
+
+    async def delete(self, key: str) -> None:
+        await cast(BaseCacheBackend, self._backend).delete(key)
+
+    async def clear(self) -> None:
+        await cast(BaseCacheBackend, self._backend).clear()
+
+    async def _make_cached_response(
+        self, cached_data: dict, req: "Request"
+    ) -> "Response":
+        req.res.body = cached_data["body"]
+        req.res.status_code = cached_data["status_code"]
+        req.res.headers = cached_data["headers"]
+        return req.res
+
+    def cache(self, duration: Optional[int] = None) -> Callable:
+        """Decorator for caching route handler results."""
+        cache = self
+
+        def decorator(handler: Callable) -> Callable:
+            @wraps(handler)
+            async def wrapper(self, *args, **kwargs) -> "Response":  # type: ignore[override]
+                req: Request = args[0]
+                method: str = req.method
+                path: str = req.path
+                query_params = sorted(req.query_params.items())
+                cache_key = f"{handler.__name__}:{method}:{path}:{hash(frozenset(query_params))}"
+
+                cached_value = await cache.get(cache_key, req)
+                if cached_value is not None:
+                    return cached_value
+
+                res: Response = await run_sync_or_async(handler, self, *args, **kwargs)
+                await cache.set(cache_key, res, duration)
+                return res
+
+            return wrapper
+
+        return decorator