msaas-cache 0.1.0__tar.gz

msaas_cache-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.local
+.env.*.local
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_cache-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: msaas-cache
+Version: 0.1.0
+Summary: Caching library with Redis and in-memory backends
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.115.0; extra == 'all'
+Requires-Dist: redis[hiredis]>=5.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fakeredis[lua]>=2.25; extra == 'dev'
+Requires-Dist: fastapi>=0.115.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
+Provides-Extra: redis
+Requires-Dist: redis[hiredis]>=5.0.0; extra == 'redis'

msaas_cache-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "msaas-cache"
+version = "0.1.0"
+description = "Caching library with Redis and in-memory backends"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+redis = ["redis[hiredis]>=5.0.0"]
+fastapi = ["fastapi>=0.115.0"]
+all = ["redis[hiredis]>=5.0.0", "fastapi>=0.115.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "fakeredis[lua]>=2.25",
+    "fastapi>=0.115.0",
+    "httpx>=0.27.0",
+    "ruff",
+    "mypy",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cache"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

msaas_cache-0.1.0/src/cache/__init__.py

@@ -0,0 +1,34 @@
+"""willian-cache: Caching library with Redis and in-memory backends."""
+
+from cache.backends.base import CacheBackend
+from cache.backends.memory_backend import MemoryBackend
+from cache.config import (
+    CacheConfig,
+    close_cache,
+    get_cache,
+    init_cache,
+    set_cache,
+)
+from cache.decorator import cached
+from cache.middleware import CacheMiddleware, cache_response
+from cache.patterns import cache_aside, cache_stampede_protection, write_through
+from cache.serialization import JsonSerializer, PickleSerializer, Serializer
+
+__all__ = [
+    "CacheBackend",
+    "CacheConfig",
+    "CacheMiddleware",
+    "JsonSerializer",
+    "MemoryBackend",
+    "PickleSerializer",
+    "Serializer",
+    "cache_aside",
+    "cache_response",
+    "cache_stampede_protection",
+    "cached",
+    "close_cache",
+    "get_cache",
+    "init_cache",
+    "set_cache",
+    "write_through",
+]

msaas_cache-0.1.0/src/cache/backends/__init__.py

@@ -0,0 +1 @@
+"""Cache backend implementations."""

msaas_cache-0.1.0/src/cache/backends/base.py

@@ -0,0 +1,63 @@
+"""Abstract cache backend interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class CacheBackend(ABC):
+    """Base class for all cache backends.
+
+    Every backend must implement the core operations: get, set, delete, exists,
+    clear.  Bulk operations (get_many, set_many, delete_many) have default
+    implementations that delegate to the single-key variants but can be
+    overridden for efficiency (e.g. Redis pipelines).
+    """
+
+    @abstractmethod
+    async def get(self, key: str) -> Any | None:
+        """Return the cached value or ``None`` if missing / expired."""
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """Store *value* under *key* with an optional TTL in seconds."""
+
+    @abstractmethod
+    async def delete(self, key: str) -> bool:
+        """Delete *key* and return ``True`` if it existed."""
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """Check whether *key* exists and is not expired."""
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Remove all keys managed by this backend."""
+
+    async def get_many(self, keys: list[str]) -> dict[str, Any]:
+        """Return a dict of key -> value for all keys that exist."""
+        result: dict[str, Any] = {}
+        for key in keys:
+            value = await self.get(key)
+            if value is not None:
+                result[key] = value
+        return result
+
+    async def set_many(
+        self, mapping: dict[str, Any], ttl: int | None = None
+    ) -> None:
+        """Set multiple key-value pairs with the same TTL."""
+        for key, value in mapping.items():
+            await self.set(key, value, ttl=ttl)
+
+    async def delete_many(self, keys: list[str]) -> int:
+        """Delete multiple keys and return count of keys that existed."""
+        count = 0
+        for key in keys:
+            if await self.delete(key):
+                count += 1
+        return count
+
+    async def close(self) -> None:
+        """Release any resources held by the backend."""

msaas_cache-0.1.0/src/cache/backends/memory_backend.py

@@ -0,0 +1,124 @@
+"""In-memory cache backend with TTL tracking and LRU eviction."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import OrderedDict
+from typing import Any
+
+from cache.backends.base import CacheBackend
+
+
+class _Entry:
+    """A cache entry with an optional expiration timestamp."""
+
+    __slots__ = ("value", "expires_at")
+
+    def __init__(self, value: Any, expires_at: float | None) -> None:
+        self.value = value
+        self.expires_at = expires_at
+
+    def is_expired(self) -> bool:
+        return self.expires_at is not None and time.monotonic() >= self.expires_at
+
+
+class MemoryBackend(CacheBackend):
+    """Dict-backed cache with per-key TTL and LRU eviction.
+
+    Args:
+        max_size: Maximum number of entries. 0 means unlimited.
+        cleanup_interval: Seconds between background cleanup sweeps. Set to 0
+            to disable automatic cleanup (expired keys are still evicted lazily
+            on access).
+    """
+
+    def __init__(
+        self,
+        max_size: int = 0,
+        cleanup_interval: float = 60.0,
+    ) -> None:
+        self._store: OrderedDict[str, _Entry] = OrderedDict()
+        self._max_size = max_size
+        self._cleanup_interval = cleanup_interval
+        self._cleanup_task: asyncio.Task[None] | None = None
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def start_cleanup(self) -> None:
+        """Start the background cleanup task if an interval is configured."""
+        if self._cleanup_interval > 0 and self._cleanup_task is None:
+            self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+
+    def _stop_cleanup(self) -> None:
+        if self._cleanup_task is not None:
+            self._cleanup_task.cancel()
+            self._cleanup_task = None
+
+    async def close(self) -> None:
+        self._stop_cleanup()
+        self._store.clear()
+
+    # -- core operations ------------------------------------------------------
+
+    async def get(self, key: str) -> Any | None:
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        if entry.is_expired():
+            del self._store[key]
+            return None
+        # Mark as recently used (move to end).
+        self._store.move_to_end(key)
+        return entry.value
+
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        expires_at = (time.monotonic() + ttl) if ttl else None
+
+        # If key already exists, update in place.
+        if key in self._store:
+            self._store[key] = _Entry(value, expires_at)
+            self._store.move_to_end(key)
+            return
+
+        # Evict LRU entries if at capacity.
+        if self._max_size > 0:
+            while len(self._store) >= self._max_size:
+                self._store.popitem(last=False)
+
+        self._store[key] = _Entry(value, expires_at)
+
+    async def delete(self, key: str) -> bool:
+        try:
+            del self._store[key]
+            return True
+        except KeyError:
+            return False
+
+    async def exists(self, key: str) -> bool:
+        entry = self._store.get(key)
+        if entry is None:
+            return False
+        if entry.is_expired():
+            del self._store[key]
+            return False
+        return True
+
+    async def clear(self) -> None:
+        self._store.clear()
+
+    # -- background cleanup ---------------------------------------------------
+
+    async def _cleanup_loop(self) -> None:
+        """Periodically sweep expired entries."""
+        try:
+            while True:
+                await asyncio.sleep(self._cleanup_interval)
+                self._sweep_expired()
+        except asyncio.CancelledError:
+            pass
+
+    def _sweep_expired(self) -> None:
+        expired = [k for k, e in self._store.items() if e.is_expired()]
+        for k in expired:
+            del self._store[k]

msaas_cache-0.1.0/src/cache/backends/redis_backend.py

@@ -0,0 +1,118 @@
+"""Redis-backed cache backend using redis.asyncio."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cache.backends.base import CacheBackend
+from cache.serialization import JsonSerializer, Serializer
+
+
+class RedisBackend(CacheBackend):
+    """Cache backend backed by Redis.
+
+    Args:
+        client: An ``redis.asyncio.Redis`` instance.
+        prefix: Key prefix / namespace applied to every key.
+        default_ttl: Default TTL in seconds when none is provided to ``set``.
+        serializer: Serializer for values. Defaults to JSON.
+    """
+
+    def __init__(
+        self,
+        client: Any,  # redis.asyncio.Redis — typed as Any to keep redis optional
+        prefix: str = "",
+        default_ttl: int = 300,
+        serializer: Serializer | None = None,
+    ) -> None:
+        self._client = client
+        self._prefix = prefix
+        self._default_ttl = default_ttl
+        self._serializer: Serializer = serializer or JsonSerializer()
+
+    def _prefixed(self, key: str) -> str:
+        if self._prefix:
+            return f"{self._prefix}:{key}"
+        return key
+
+    # -- core operations ------------------------------------------------------
+
+    async def get(self, key: str) -> Any | None:
+        raw: bytes | None = await self._client.get(self._prefixed(key))
+        if raw is None:
+            return None
+        return self._serializer.loads(raw)
+
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        effective_ttl = ttl if ttl is not None else self._default_ttl
+        data = self._serializer.dumps(value)
+        if effective_ttl > 0:
+            await self._client.setex(self._prefixed(key), effective_ttl, data)
+        else:
+            await self._client.set(self._prefixed(key), data)
+
+    async def delete(self, key: str) -> bool:
+        result = await self._client.delete(self._prefixed(key))
+        return bool(result)
+
+    async def exists(self, key: str) -> bool:
+        result = await self._client.exists(self._prefixed(key))
+        return bool(result)
+
+    async def clear(self) -> None:
+        if self._prefix:
+            pattern = f"{self._prefix}:*"
+            cursor: int | bytes = 0
+            while True:
+                cursor, keys = await self._client.scan(
+                    cursor=cursor, match=pattern, count=100
+                )
+                if keys:
+                    await self._client.delete(*keys)
+                if cursor == 0:
+                    break
+        else:
+            await self._client.flushdb()
+
+    # -- bulk operations via pipeline -----------------------------------------
+
+    async def get_many(self, keys: list[str]) -> dict[str, Any]:
+        if not keys:
+            return {}
+        prefixed = [self._prefixed(k) for k in keys]
+        pipe = self._client.pipeline()
+        for pk in prefixed:
+            pipe.get(pk)
+        results = await pipe.execute()
+
+        output: dict[str, Any] = {}
+        for key, raw in zip(keys, results):
+            if raw is not None:
+                output[key] = self._serializer.loads(raw)
+        return output
+
+    async def set_many(
+        self, mapping: dict[str, Any], ttl: int | None = None
+    ) -> None:
+        if not mapping:
+            return
+        effective_ttl = ttl if ttl is not None else self._default_ttl
+        pipe = self._client.pipeline()
+        for key, value in mapping.items():
+            data = self._serializer.dumps(value)
+            pk = self._prefixed(key)
+            if effective_ttl > 0:
+                pipe.setex(pk, effective_ttl, data)
+            else:
+                pipe.set(pk, data)
+        await pipe.execute()
+
+    async def delete_many(self, keys: list[str]) -> int:
+        if not keys:
+            return 0
+        prefixed = [self._prefixed(k) for k in keys]
+        result = await self._client.delete(*prefixed)
+        return int(result)
+
+    async def close(self) -> None:
+        await self._client.aclose()

msaas_cache-0.1.0/src/cache/config.py

@@ -0,0 +1,105 @@
+"""Cache configuration and global instance management."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from cache.backends.base import CacheBackend
+from cache.serialization import JsonSerializer, Serializer
+
+
+class BackendType(str, Enum):
+    MEMORY = "memory"
+    REDIS = "redis"
+
+
+class CacheConfig(BaseModel):
+    """Configuration for the cache system.
+
+    Attributes:
+        backend: Which backend to use (``memory`` or ``redis``).
+        redis_url: Redis connection URL (only used when ``backend="redis"``).
+        default_ttl: Default TTL in seconds for cache entries.
+        key_prefix: Namespace prefix applied to all keys.
+        max_memory_items: Maximum items for the in-memory backend (0 = unlimited).
+        serializer_type: ``"json"`` or ``"pickle"``.
+    """
+
+    backend: BackendType = BackendType.MEMORY
+    redis_url: str = "redis://localhost:6379"
+    default_ttl: int = Field(default=300, ge=0)
+    key_prefix: str = ""
+    max_memory_items: int = Field(default=0, ge=0)
+    serializer_type: str = "json"
+
+
+# -- global state -------------------------------------------------------------
+
+_backend: CacheBackend | None = None
+
+
+def _build_serializer(name: str) -> Serializer:
+    if name == "pickle":
+        from cache.serialization import PickleSerializer
+
+        return PickleSerializer()
+    return JsonSerializer()
+
+
+def init_cache(config: CacheConfig | None = None) -> CacheBackend:
+    """Initialize the global cache backend from config.
+
+    Returns the created backend instance.
+    """
+    global _backend
+    cfg = config or CacheConfig()
+    serializer = _build_serializer(cfg.serializer_type)
+
+    if cfg.backend == BackendType.REDIS:
+        try:
+            import redis.asyncio as redis
+        except ImportError as exc:
+            raise ImportError(
+                "Install willian-cache[redis] to use the Redis backend."
+            ) from exc
+
+        client = redis.from_url(cfg.redis_url, decode_responses=False)
+        from cache.backends.redis_backend import RedisBackend
+
+        _backend = RedisBackend(
+            client=client,
+            prefix=cfg.key_prefix,
+            default_ttl=cfg.default_ttl,
+            serializer=serializer,
+        )
+    else:
+        from cache.backends.memory_backend import MemoryBackend
+
+        _backend = MemoryBackend(max_size=cfg.max_memory_items)
+        _backend.start_cleanup()
+
+    return _backend
+
+
+def get_cache() -> CacheBackend:
+    """Return the active cache backend. Raises if not initialized."""
+    if _backend is None:
+        raise RuntimeError("Cache not initialized. Call init_cache() first.")
+    return _backend
+
+
+def set_cache(backend: CacheBackend) -> None:
+    """Override the global cache backend (useful for testing)."""
+    global _backend
+    _backend = backend
+
+
+async def close_cache() -> None:
+    """Close the global cache backend and release resources."""
+    global _backend
+    if _backend is not None:
+        await _backend.close()
+        _backend = None

msaas_cache-0.1.0/src/cache/decorator.py

@@ -0,0 +1,113 @@
+"""Caching decorator for async functions."""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+import json
+from typing import Any, Callable
+
+from cache.config import get_cache
+
+
+def _default_key_builder(
+    func: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    prefix: str,
+) -> str:
+    """Build a cache key from function name + arguments.
+
+    Produces a deterministic, human-readable key like:
+        ``prefix:module.func_name:sha256_of_args``
+    """
+    func_id = f"{func.__module__}.{func.__qualname__}"
+
+    # Bind arguments to get a consistent representation.
+    sig = inspect.signature(func)
+    bound = sig.bind(*args, **kwargs)
+    bound.apply_defaults()
+    args_str = json.dumps(
+        {k: repr(v) for k, v in bound.arguments.items()},
+        sort_keys=True,
+    )
+    args_hash = hashlib.sha256(args_str.encode()).hexdigest()[:16]
+
+    parts = [p for p in (prefix, func_id, args_hash) if p]
+    return ":".join(parts)
+
+
+def cached(
+    ttl: int = 300,
+    key_prefix: str = "",
+    key_builder: Callable[..., str] | None = None,
+    condition: Callable[[Any], bool] | None = None,
+) -> Callable[..., Any]:
+    """Decorator that caches the return value of an async function.
+
+    Args:
+        ttl: Time-to-live in seconds for the cached result.
+        key_prefix: Static prefix for cache keys.
+        key_builder: Custom ``(func, args, kwargs) -> str`` key builder.
+            Overrides the default key generation when provided.
+        condition: Optional predicate ``(result) -> bool``. The result is
+            only cached when condition returns ``True``.
+
+    Usage::
+
+        @cached(ttl=60, key_prefix="users")
+        async def get_user(user_id: str) -> dict:
+            ...
+
+        # Invalidate a specific call
+        await get_user.invalidate("user_123")
+
+        # Custom key builder
+        @cached(key_builder=lambda fn, args, kw: f"custom:{args[0]}")
+        async def lookup(query: str) -> list:
+            ...
+
+        # Conditional caching (skip None results)
+        @cached(condition=lambda r: r is not None)
+        async def find_user(email: str) -> dict | None:
+            ...
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            cache = get_cache()
+
+            if key_builder is not None:
+                cache_key = key_builder(func, args, kwargs)
+            else:
+                cache_key = _default_key_builder(func, args, kwargs, key_prefix)
+
+            # Check cache first.
+            hit = await cache.get(cache_key)
+            if hit is not None:
+                return hit
+
+            # Cache miss — call the original function.
+            result = await func(*args, **kwargs)
+
+            # Conditionally cache the result.
+            if condition is None or condition(result):
+                await cache.set(cache_key, result, ttl=ttl)
+
+            return result
+
+        async def invalidate(*args: Any, **kwargs: Any) -> bool:
+            """Invalidate the cached result for the given arguments."""
+            cache = get_cache()
+            if key_builder is not None:
+                cache_key = key_builder(func, args, kwargs)
+            else:
+                cache_key = _default_key_builder(func, args, kwargs, key_prefix)
+            return await cache.delete(cache_key)
+
+        wrapper.invalidate = invalidate  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator