fastlib-py 0.1.0__py3-none-any.whl

fastlib/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""Fast Web Application Libraries Package."""

fastlib/cache/__init__.py

@@ -0,0 +1,7 @@
+"""Provides a unified cache client based on configuration."""
+
+from .cache_manager import get_cache_client
+
+__all__ = [
+    get_cache_client,
+]

fastlib/cache/base_cache.py

@@ -0,0 +1,175 @@
+"""
+Base cache interface providing a unified caching abstraction.
+
+This module defines the base Cache class that provides a common interface
+for different caching implementations like Redis, memory cache, etc.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from contextlib import asynccontextmanager
+
+
+class CacheError(Exception):
+    """Custom exception for cache-related errors."""
+
+    def __init__(self, message: str, original_error: Optional[Exception] = None):
+        self.message = message
+        self.original_error = original_error
+        super().__init__(f"Cache Error: {message}")
+
+
+class Cache(ABC):
+    """
+    Abstract base class for cache implementations.
+    
+    This class defines the interface that all cache implementations must follow,
+    providing a unified API for caching operations across different backends.
+    """
+
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Test cache connection/availability."""
+        pass
+
+    @abstractmethod
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ex: Optional[int] = None,
+        nx: bool = False,
+        xx: bool = False,
+    ) -> bool:
+        """Set a key-value pair in cache."""
+        pass
+
+    @abstractmethod
+    async def get(self, key: str) -> Optional[Any]:
+        """Get a value from cache."""
+        pass
+
+    @abstractmethod
+    async def delete(self, *keys: str) -> int:
+        """Delete one or more keys from cache."""
+        pass
+
+    @abstractmethod
+    async def exists(self, *keys: str) -> int:
+        """Check if keys exist in cache."""
+        pass
+
+    @abstractmethod
+    async def expire(self, key: str, seconds: int) -> bool:
+        """Set expiration time for a key."""
+        pass
+
+    @abstractmethod
+    async def ttl(self, key: str) -> int:
+        """Get time to live for a key."""
+        pass
+
+    @abstractmethod
+    async def incr(self, key: str, amount: int = 1) -> int:
+        """Increment a counter in cache."""
+        pass
+
+    @abstractmethod
+    async def decr(self, key: str, amount: int = 1) -> int:
+        """Decrement a counter in cache."""
+        pass
+
+    @abstractmethod
+    async def hset(self, name: str, key: str, value: Any) -> int:
+        """Set a field in a hash."""
+        pass
+
+    @abstractmethod
+    async def hget(self, name: str, key: str) -> Optional[Any]:
+        """Get a field from a hash."""
+        pass
+
+    @abstractmethod
+    async def hgetall(self, name: str) -> Dict[str, Any]:
+        """Get all fields from a hash."""
+        pass
+
+    @abstractmethod
+    async def hdel(self, name: str, *keys: str) -> int:
+        """Delete fields from a hash."""
+        pass
+
+    @abstractmethod
+    async def lpush(self, name: str, *values: Any) -> int:
+        """Push values to the left of a list."""
+        pass
+
+    @abstractmethod
+    async def rpush(self, name: str, *values: Any) -> int:
+        """Push values to the right of a list."""
+        pass
+
+    @abstractmethod
+    async def lpop(self, name: str) -> Optional[Any]:
+        """Pop a value from the left of a list."""
+        pass
+
+    @abstractmethod
+    async def rpop(self, name: str) -> Optional[Any]:
+        """Pop a value from the right of a list."""
+        pass
+
+    @abstractmethod
+    async def lrange(self, name: str, start: int = 0, end: int = -1) -> List[Any]:
+        """Get a range of values from a list."""
+        pass
+
+    @abstractmethod
+    async def sadd(self, name: str, *values: Any) -> int:
+        """Add values to a set."""
+        pass
+
+    @abstractmethod
+    async def smembers(self, name: str) -> List[Any]:
+        """Get all members of a set."""
+        pass
+
+    @abstractmethod
+    async def srem(self, name: str, *values: Any) -> int:
+        """Remove values from a set."""
+        pass
+
+    @abstractmethod
+    async def acquire_lock(
+        self,
+        lock_name: str,
+        timeout: int = 10,
+        blocking_timeout: int = 5,
+        thread_local: bool = True,
+    ) -> bool:
+        """Acquire a distributed lock."""
+        pass
+
+    @abstractmethod
+    async def release_lock(self, lock_name: str) -> bool:
+        """Release a distributed lock."""
+        pass
+
+    @abstractmethod
+    @asynccontextmanager
+    async def lock(self, lock_name: str, timeout: int = 10, blocking_timeout: int = 5):
+        """Context manager for distributed locks."""
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close cache connections."""
+        pass
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()

fastlib/cache/cache_manager.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+"""Cache Client manager to instantiate the appropriate cache client"""
+
+from fastlib.cache.base_cache import Cache
+from fastlib.cache.redis_cache import RedisManager
+from fastlib.config.manager import ConfigManager
+
+
+async def get_cache_client() -> Cache:
+    """Initialize and return the appropriate cache client based on configuration.
+
+    Returns:
+        Cache: Redis client if Redis is enabled in config, otherwise returns page cache.
+    """
+
+    config = ConfigManager.get_database_config()
+    if config.enable_redis:
+        from fastlib.cache.redis_cache import RedisCache
+
+        redis_client = await RedisManager.get_instance()
+        return RedisCache(redis_client)
+    else:
+        from fastlib.cache.disk_cache import PageCache
+
+        return PageCache()

fastlib/cache/disk_cache.py

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: MIT
+"""DiskCache-based PageCache implementation compatible with Cache interface."""
+
+from contextlib import asynccontextmanager
+import json
+import time
+import threading
+from typing import Any, Dict, List, Optional, Union
+import diskcache
+
+from fastlib.cache.base_cache import Cache, CacheError
+
+
+class PageCache(Cache):
+    def __init__(self, directory: str = "./.diskcache"):
+        self.cache = diskcache.Cache(directory)
+        self._locks: Dict[str, threading.Lock] = {}
+
+    async def ping(self) -> bool:
+        try:
+            self.cache.set("__ping__", "pong", expire=1)
+            return True
+        except Exception as e:
+            raise CacheError("Ping failed", e)
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ex: Optional[int] = None,
+        nx: bool = False,  # only set if not exists
+        xx: bool = False,  # only set if exists
+    ) -> bool:
+        if nx and key in self.cache:
+            return False
+        if xx and key not in self.cache:
+            return False
+        return self.cache.set(key, value, expire=ex)
+
+    async def get(self, key: str) -> Optional[Any]:
+        return self.cache.get(key, None)
+
+    async def delete(self, *keys: str) -> int:
+        count = 0
+        for k in keys:
+            if k in self.cache:
+                self.cache.delete(k)
+                count += 1
+        return count
+
+    async def exists(self, *keys: str) -> int:
+        return sum(1 for k in keys if k in self.cache)
+
+    async def expire(self, key: str, seconds: int) -> bool:
+        if key not in self.cache:
+            return False
+        value = self.cache.get(key)
+        self.cache.set(key, value, expire=seconds)
+        return True
+
+    async def ttl(self, key: str) -> int:
+        if key not in self.cache:
+            return -2  # Redis convention: -2 means key does not exist
+        expiry = self.cache.ttl(key)
+        return int(expiry) if expiry is not None else -1  # -1 means no expiry
+
+    async def incr(self, key: str, amount: int = 1) -> int:
+        with self.cache.transact():
+            val = self.cache.get(key, 0)
+            if not isinstance(val, int):
+                raise CacheError("Value is not integer")
+            val += amount
+            self.cache.set(key, val)
+            return val
+
+    async def decr(self, key: str, amount: int = 1) -> int:
+        return await self.incr(key, -amount)
+
+    # ---------------- Hash (dict) ----------------
+    async def hset(self, name: str, key: str, value: Any) -> int:
+        data = self.cache.get(name, {})
+        if not isinstance(data, dict):
+            data = {}
+        data[key] = value
+        self.cache.set(name, data)
+        return 1
+
+    async def hget(self, name: str, key: str) -> Optional[Any]:
+        data = self.cache.get(name, {})
+        return data.get(key) if isinstance(data, dict) else None
+
+    async def hgetall(self, name: str) -> Dict[str, Any]:
+        data = self.cache.get(name, {})
+        return data if isinstance(data, dict) else {}
+
+    async def hdel(self, name: str, *keys: str) -> int:
+        data = self.cache.get(name, {})
+        if not isinstance(data, dict):
+            return 0
+        removed = 0
+        for k in keys:
+            if k in data:
+                del data[k]
+                removed += 1
+        self.cache.set(name, data)
+        return removed
+
+    # ---------------- List ----------------
+    def _get_list(self, key: str) -> List[Any]:
+        data = self.cache.get(key)
+        if data is None:
+            return []
+        if isinstance(data, str):  # if JSON stored
+            try:
+                return json.loads(data)
+            except Exception:
+                return []
+        if isinstance(data, list):
+            return data
+        return []
+
+    def _set_list(self, key: str, value: List[Any]):
+        self.cache.set(key, json.dumps(value))
+
+    async def lpush(self, name: str, *values: Any) -> int:
+        lst = self._get_list(name)
+        for v in values:
+            lst.insert(0, v)
+        self._set_list(name, lst)
+        return len(lst)
+
+    async def rpush(self, name: str, *values: Any) -> int:
+        lst = self._get_list(name)
+        lst.extend(values)
+        self._set_list(name, lst)
+        return len(lst)
+
+    async def lpop(self, name: str) -> Optional[Any]:
+        lst = self._get_list(name)
+        if not lst:
+            return None
+        val = lst.pop(0)
+        self._set_list(name, lst)
+        return val
+
+    async def rpop(self, name: str) -> Optional[Any]:
+        lst = self._get_list(name)
+        if not lst:
+            return None
+        val = lst.pop()
+        self._set_list(name, lst)
+        return val
+
+    async def lrange(self, name: str, start: int = 0, end: int = -1) -> List[Any]:
+        lst = self._get_list(name)
+        if end == -1:
+            end = len(lst) - 1
+        return lst[start : end + 1]
+
+    # ---------------- Set ----------------
+    async def sadd(self, name: str, *values: Any) -> int:
+        current = self.cache.get(name, set())
+        if not isinstance(current, set):
+            current = set()
+        before = len(current)
+        current.update(values)
+        self.cache.set(name, current)
+        return len(current) - before
+
+    async def smembers(self, name: str) -> List[Any]:
+        current = self.cache.get(name, set())
+        return list(current) if isinstance(current, set) else []
+
+    async def srem(self, name: str, *values: Any) -> int:
+        current = self.cache.get(name, set())
+        if not isinstance(current, set):
+            return 0
+        before = len(current)
+        for v in values:
+            current.discard(v)
+        self.cache.set(name, current)
+        return before - len(current)
+
+    # ---------------- Lock (simple thread-based) ----------------
+    async def acquire_lock(
+        self, lock_name: str, timeout: int = 10, blocking_timeout: int = 5, thread_local: bool = True
+    ) -> bool:
+        lock = self._locks.setdefault(lock_name, threading.Lock())
+        start = time.time()
+        while time.time() - start < blocking_timeout:
+            if lock.acquire(blocking=False):
+                return True
+            time.sleep(0.05)
+        return False
+
+    async def release_lock(self, lock_name: str) -> bool:
+        lock = self._locks.get(lock_name)
+        if lock and lock.locked():
+            lock.release()
+            return True
+        return False
+
+    @asynccontextmanager
+    async def lock(self, lock_name: str, timeout: int = 10, blocking_timeout: int = 5):
+        acquired = await self.acquire_lock(lock_name, timeout, blocking_timeout)
+        if not acquired:
+            raise CacheError(f"Failed to acquire lock: {lock_name}")
+        try:
+            yield
+        finally:
+            await self.release_lock(lock_name)
+
+    async def close(self) -> None:
+        self.cache.close()