hypern 0.3.11__cp311-cp311-musllinux_1_2_armv7l.whl

hypern/caching/redis_backend.py

@@ -0,0 +1,201 @@
+# src/hypern/cache/backends/redis.py
+import pickle
+from typing import Any, Optional
+
+from redis import asyncio as aioredis
+
+from hypern.logging import logger
+
+from .backend import BaseBackend
+
+
+class RedisBackend(BaseBackend):
+    def __init__(self, url: str = "redis://localhost:6379", encoding: str = "utf-8", decode_responses: bool = False, **kwargs):
+        """
+        Initialize Redis backend with aioredis
+
+        Args:
+            url: Redis connection URL
+            encoding: Character encoding to use
+            decode_responses: Whether to decode response bytes to strings
+            **kwargs: Additional arguments passed to aioredis.from_url
+        """
+        self.redis = aioredis.from_url(url, encoding=encoding, decode_responses=decode_responses, **kwargs)
+        self._encoding = encoding
+
+    async def get(self, key: str) -> Optional[Any]:
+        """
+        Get value from Redis
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Deserialized Python object or None if key doesn't exist
+        """
+        try:
+            value = await self.redis.get(key)
+            if value is not None:
+                return pickle.loads(value)
+            return None
+        except Exception as e:
+            logger.error(f"Error getting cache key {key}: {e}")
+            return None
+
+    async def set(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        """
+        Set value in Redis with optional TTL
+
+        Args:
+            key: Cache key
+            value: Python object to store
+            ttl: Time to live in seconds
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            serialized = pickle.dumps(value)
+            if ttl is not None:
+                await self.redis.setex(key, ttl, serialized)
+            else:
+                await self.redis.set(key, serialized)
+            return True
+        except Exception as e:
+            logger.error(f"Error setting cache key {key}: {e}")
+            return False
+
+    async def delete(self, key: str) -> bool:
+        """
+        Delete key from Redis
+
+        Args:
+            key: Cache key to delete
+
+        Returns:
+            bool: True if key was deleted, False otherwise
+        """
+        try:
+            return bool(await self.redis.delete(key))
+        except Exception as e:
+            logger.error(f"Error deleting cache key {key}: {e}")
+            return False
+
+    async def delete_pattern(self, pattern: str) -> int:
+        """
+        Delete all keys matching pattern
+
+        Args:
+            pattern: Redis key pattern to match
+
+        Returns:
+            int: Number of keys deleted
+        """
+        try:
+            keys = await self.redis.keys(pattern)
+            if keys:
+                return await self.redis.delete(*keys)
+            return 0
+        except Exception as e:
+            logger.error(f"Error deleting keys matching {pattern}: {e}")
+            return 0
+
+    async def exists(self, key: str) -> bool:
+        """
+        Check if key exists
+
+        Args:
+            key: Cache key to check
+
+        Returns:
+            bool: True if key exists, False otherwise
+        """
+        try:
+            return bool(await self.redis.exists(key))
+        except Exception as e:
+            logger.error(f"Error checking existence of key {key}: {e}")
+            return False
+
+    async def ttl(self, key: str) -> int:
+        """
+        Get TTL of key in seconds
+
+        Args:
+            key: Cache key
+
+        Returns:
+            int: TTL in seconds, -2 if key doesn't exist, -1 if key has no TTL
+        """
+        try:
+            return await self.redis.ttl(key)
+        except Exception as e:
+            logger.error(f"Error getting TTL for key {key}: {e}")
+            return -2
+
+    async def incr(self, key: str, amount: int = 1) -> Optional[int]:
+        """
+        Increment value by amount
+
+        Args:
+            key: Cache key
+            amount: Amount to increment by
+
+        Returns:
+            int: New value after increment or None on error
+        """
+        try:
+            return await self.redis.incrby(key, amount)
+        except Exception as e:
+            logger.error(f"Error incrementing key {key}: {e}")
+            return None
+
+    async def set_nx(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        """
+        Set key only if it doesn't exist (SET NX operation)
+
+        Args:
+            key: Cache key
+            value: Value to set
+            ttl: Optional TTL in seconds
+
+        Returns:
+            bool: True if key was set, False otherwise
+        """
+        try:
+            serialized = pickle.dumps(value)
+            if ttl is not None:
+                return await self.redis.set(key, serialized, nx=True, ex=ttl)
+            return await self.redis.set(key, serialized, nx=True)
+        except Exception as e:
+            logger.error(f"Error setting NX for key {key}: {e}")
+            return False
+
+    async def clear(self) -> bool:
+        """
+        Clear all keys from the current database
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            await self.redis.flushdb()
+            return True
+        except Exception as e:
+            logger.error(f"Error clearing cache: {e}")
+            return False
+
+    async def close(self) -> None:
+        """Close Redis connection"""
+        await self.redis.close()
+
+    async def ping(self) -> bool:
+        """
+        Check Redis connection
+
+        Returns:
+            bool: True if connection is alive, False otherwise
+        """
+        try:
+            return await self.redis.ping()
+        except Exception:
+            return False

hypern/caching/strategies.py

@@ -0,0 +1,208 @@
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from typing import Callable, Generic, Optional, TypeVar
+
+import orjson
+
+from .backend import BaseBackend
+
+T = TypeVar("T")
+
+
+class CacheStrategy(ABC, Generic[T]):
+    """Base class for cache strategies"""
+
+    @abstractmethod
+    async def get(self, key: str) -> Optional[T]:
+        pass
+
+    @abstractmethod
+    async def set(self, key: str, value: T, ttl: Optional[int] = None) -> None:
+        pass
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        pass
+
+
+class CacheEntry(Generic[T]):
+    """Represents a cached item with metadata"""
+
+    def __init__(self, value: T, created_at: float, ttl: int, revalidate_after: Optional[int] = None):
+        self.value = value
+        self.created_at = created_at
+        self.ttl = ttl
+        self.revalidate_after = revalidate_after
+        self.is_revalidating = False
+
+    def is_stale(self) -> bool:
+        """Check if entry is stale and needs revalidation"""
+        now = time.time()
+        return self.revalidate_after is not None and now > (self.created_at + self.revalidate_after)
+
+    def is_expired(self) -> bool:
+        """Check if entry has completely expired"""
+        now = time.time()
+        return now > (self.created_at + self.ttl)
+
+    def to_json(self) -> bytes:
+        """Serialize entry to JSON"""
+        return orjson.dumps(
+            {
+                "value": self.value,
+                "created_at": self.created_at,
+                "ttl": self.ttl,
+                "revalidate_after": self.revalidate_after,
+                "is_revalidating": self.is_revalidating,
+            }
+        )
+
+    @classmethod
+    def from_json(cls, data: bytes) -> "CacheEntry[T]":
+        """Deserialize entry from JSON"""
+        parsed = orjson.loads(data)
+        return cls(value=parsed["value"], created_at=parsed["created_at"], ttl=parsed["ttl"], revalidate_after=parsed["revalidate_after"])
+
+
+class StaleWhileRevalidateStrategy(CacheStrategy[T]):
+    """
+    Implements stale-while-revalidate caching strategy.
+    Allows serving stale content while revalidating in the background.
+    """
+
+    def __init__(self, backend: BaseBackend, revalidate_after: int, ttl: int, revalidate_fn: Callable[..., T]):
+        """
+        Initialize the caching strategy.
+
+        Args:
+            backend (BaseBackend): The backend storage for caching.
+            revalidate_after (int): The time in seconds after which the cache should be revalidated.
+            ttl (int): The time-to-live for cache entries in seconds.
+            revalidate_fn (Callable[..., T]): The function to call for revalidating the cache.
+
+        Attributes:
+            backend (BaseBackend): The backend storage for caching.
+            revalidate_after (int): The time in seconds after which the cache should be revalidated.
+            ttl (int): The time-to-live for cache entries in seconds.
+            revalidate_fn (Callable[..., T]): The function to call for revalidating the cache.
+            _revalidation_locks (dict): A dictionary to manage revalidation locks.
+        """
+        self.backend = backend
+        self.revalidate_after = revalidate_after
+        self.ttl = ttl
+        self.revalidate_fn = revalidate_fn
+        self._revalidation_locks: dict = {}
+
+    async def get(self, key: str) -> Optional[T]:
+        entry = await self.backend.get(key)
+        if not entry:
+            return None
+
+        if isinstance(entry, bytes):
+            entry = CacheEntry.from_json(entry)
+
+        # If entry is stale but not expired, trigger background revalidation
+        if entry.is_stale() and not entry.is_expired():
+            if not entry.is_revalidating:
+                entry.is_revalidating = True
+                await self.backend.set(key, entry.to_json())
+                asyncio.create_task(self._revalidate(key))
+            return entry.value
+
+        # If entry is expired, return None
+        if entry.is_expired():
+            return None
+
+        return entry.value
+
+    async def set(self, key: str, value: T, ttl: Optional[int] = None) -> None:
+        entry = CacheEntry(value=value, created_at=time.time(), ttl=ttl or self.ttl, revalidate_after=self.revalidate_after)
+        await self.backend.set(key, entry.to_json(), ttl=ttl)
+
+    async def delete(self, key: str) -> None:
+        await self.backend.delete(key)
+
+    async def _revalidate(self, key: str) -> None:
+        """Background revalidation of cached data"""
+        try:
+            # Prevent multiple simultaneous revalidations
+            if key in self._revalidation_locks:
+                return
+            self._revalidation_locks[key] = True
+
+            # Get fresh data
+            fresh_value = await self.revalidate_fn(key)
+
+            # Update cache with fresh data
+            await self.set(key, fresh_value)
+        finally:
+            self._revalidation_locks.pop(key, None)
+
+
+class CacheAsideStrategy(CacheStrategy[T]):
+    """
+    Implements cache-aside (lazy loading) strategy.
+    Data is loaded into cache only when requested.
+    """
+
+    def __init__(self, backend: BaseBackend, load_fn: Callable[[str], T], ttl: int, write_through: bool = False):
+        self.backend = backend
+        self.load_fn = load_fn
+        self.ttl = ttl
+        self.write_through = write_through
+
+    async def get(self, key: str) -> Optional[T]:
+        # Try to get from cache first
+        value = await self.backend.get(key)
+        if value:
+            if isinstance(value, bytes):
+                value = orjson.loads(value)
+            return value
+
+        # On cache miss, load from source
+        value = await self.load_fn(key)
+        if value is not None:
+            await self.set(key, value)
+        return value
+
+    async def set(self, key: str, value: T, ttl: Optional[int] = None) -> None:
+        await self.backend.set(key, value, ttl or self.ttl)
+
+        # If write-through is enabled, update the source
+        if self.write_through:
+            await self._write_to_source(key, value)
+
+    async def delete(self, key: str) -> None:
+        await self.backend.delete(key)
+
+    async def _write_to_source(self, key: str, value: T) -> None:
+        """Write to the source in write-through mode"""
+        if hasattr(self.load_fn, "write"):
+            await self.load_fn.write(key, value)
+
+
+def cache_with_strategy(strategy: CacheStrategy, key_prefix: str | None = None, ttl: int = 3600):
+    """
+    Decorator for using cache strategies
+    """
+
+    def decorator(func):
+        async def wrapper(*args, **kwargs):
+            # Generate cache key
+            cache_key = f"{key_prefix or func.__name__}:{hash(str(args) + str(kwargs))}"
+
+            result = await strategy.get(cache_key)
+            if result is not None:
+                return result
+
+            # Execute function and cache result
+            result = await func(*args, **kwargs)
+            if result is not None:
+                await strategy.set(cache_key, result, ttl)
+
+            return result
+
+        return wrapper
+
+    return decorator

hypern/config.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import os
+
+# -*- coding: utf-8 -*-
+import threading
+import typing
+import warnings
+from contextvars import ContextVar
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Optional
+
+"""
+
+refer: https://github.com/encode/starlette/blob/master/starlette/config.py
+# Config will be read from environment variables and/or ".env" files.
+config = Config(".env")
+
+DEBUG = config('DEBUG', cast=bool, default=False)
+DATABASE_URL = config('DATABASE_URL')
+ALLOWED_HOSTS = config('ALLOWED_HOSTS', cast=CommaSeparatedStrings)
+"""
+
+
+class undefined:
+    pass
+
+
+class EnvironError(Exception):
+    pass
+
+
+class Environ(typing.MutableMapping[str, str]):
+    def __init__(self, environ: typing.MutableMapping[str, str] = os.environ):
+        self._environ = environ
+        self._has_been_read: set[str] = set()
+
+    def __getitem__(self, key: str) -> str:
+        self._has_been_read.add(key)
+        return self._environ.__getitem__(key)
+
+    def __setitem__(self, key: str, value: str) -> None:
+        if key in self._has_been_read:
+            raise EnvironError(f"Attempting to set environ['{key}'], but the value has already been read.")
+        self._environ.__setitem__(key, value)
+
+    def __delitem__(self, key: str) -> None:
+        if key in self._has_been_read:
+            raise EnvironError(f"Attempting to delete environ['{key}'], but the value has already been read.")
+        self._environ.__delitem__(key)
+
+    def __iter__(self) -> typing.Iterator[str]:
+        return iter(self._environ)
+
+    def __len__(self) -> int:
+        return len(self._environ)
+
+
+environ = Environ()
+
+T = typing.TypeVar("T")
+
+
+class Config:
+    def __init__(
+        self,
+        env_file: str | Path | None = None,
+        environ: typing.Mapping[str, str] = environ,
+        env_prefix: str = "",
+    ) -> None:
+        self.environ = environ
+        self.env_prefix = env_prefix
+        self.file_values: dict[str, str] = {}
+        if env_file is not None:
+            if not os.path.isfile(env_file):
+                warnings.warn(f"Config file '{env_file}' not found.")
+            else:
+                self.file_values = self._read_file(env_file)
+
+    @typing.overload
+    def __call__(self, key: str, *, default: None) -> str | None: ...
+
+    @typing.overload
+    def __call__(self, key: str, cast: type[T], default: T = ...) -> T: ...
+
+    @typing.overload
+    def __call__(self, key: str, cast: type[str] = ..., default: str = ...) -> str: ...
+
+    @typing.overload
+    def __call__(
+        self,
+        key: str,
+        cast: typing.Callable[[typing.Any], T] = ...,
+        default: typing.Any = ...,
+    ) -> T: ...
+
+    @typing.overload
+    def __call__(self, key: str, cast: type[str] = ..., default: T = ...) -> T | str: ...
+
+    def __call__(
+        self,
+        key: str,
+        cast: typing.Callable[[typing.Any], typing.Any] | None = None,
+        default: typing.Any = undefined,
+    ) -> typing.Any:
+        return self.get(key, cast, default)
+
+    def get(
+        self,
+        key: str,
+        cast: typing.Callable[[typing.Any], typing.Any] | None = None,
+        default: typing.Any = undefined,
+    ) -> typing.Any:
+        key = self.env_prefix + key
+        if key in self.environ:
+            value = self.environ[key]
+            return self._perform_cast(key, value, cast)
+        if key in self.file_values:
+            value = self.file_values[key]
+            return self._perform_cast(key, value, cast)
+        if default is not undefined:
+            return self._perform_cast(key, default, cast)
+        raise KeyError(f"Config '{key}' is missing, and has no default.")
+
+    def _read_file(self, file_name: str | Path) -> dict[str, str]:
+        file_values: dict[str, str] = {}
+        with open(file_name) as input_file:
+            for line in input_file.readlines():
+                line = line.strip()
+                if "=" in line and not line.startswith("#"):
+                    key, value = line.split("=", 1)
+                    key = key.strip()
+                    value = value.strip().strip("\"'")
+                    file_values[key] = value
+        return file_values
+
+    def _perform_cast(
+        self,
+        key: str,
+        value: typing.Any,
+        cast: typing.Callable[[typing.Any], typing.Any] | None = None,
+    ) -> typing.Any:
+        if cast is None or value is None:
+            return value
+        elif cast is bool and isinstance(value, str):
+            mapping = {"true": True, "1": True, "false": False, "0": False}
+            value = value.lower()
+            if value not in mapping:
+                raise ValueError(f"Config '{key}' has value '{value}'. Not a valid bool.")
+            return mapping[value]
+        try:
+            return cast(value)
+        except (TypeError, ValueError):
+            raise ValueError(f"Config '{key}' has value '{value}'. Not a valid {cast.__name__}.")
+
+
+class ContextStore:
+    def __init__(self, cleanup_interval: int = 300, max_age: int = 3600):
+        """
+        Initialize ContextStore with automatic session cleanup.
+
+        :param cleanup_interval: Interval between cleanup checks (in seconds)
+        :param max_age: Maximum age of a session before it's considered expired (in seconds)
+        """
+        self._session_times: Dict[str, datetime] = {}
+        self.session_var = ContextVar("session_id", default=None)
+
+        self._max_age = max_age
+        self._cleanup_interval = cleanup_interval
+        self._cleanup_thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+
+        # Start the cleanup thread
+        self._start_cleanup_thread()
+
+    def _start_cleanup_thread(self):
+        """Start a background thread for periodic session cleanup."""
+
+        def cleanup_worker():
+            while not self._stop_event.is_set():
+                self._perform_cleanup()
+                self._stop_event.wait(self._cleanup_interval)
+
+        self._cleanup_thread = threading.Thread(
+            target=cleanup_worker,
+            daemon=True,  # Allows the thread to be automatically terminated when the main program exits
+        )
+        self._cleanup_thread.start()
+
+    def _perform_cleanup(self):
+        """Perform cleanup of expired sessions."""
+        current_time = datetime.now()
+        expired_sessions = [
+            session_id for session_id, timestamp in list(self._session_times.items()) if (current_time - timestamp).total_seconds() > self._max_age
+        ]
+
+        for session_id in expired_sessions:
+            self.remove_session(session_id)
+
+    def remove_session(self, session_id: str):
+        """Remove a specific session."""
+        self._session_times.pop(session_id, None)
+
+    def set_context(self, session_id: str):
+        """
+        Context manager for setting and resetting session context.
+
+        :param session_id: Unique identifier for the session
+        :return: Context manager for session
+        """
+        self.session_var.set(session_id)
+        self._session_times[session_id] = datetime.now()
+
+    def get_context(self) -> str:
+        """
+        Get the current session context.
+
+        :return: Current session ID
+        :raises RuntimeError: If no session context is available
+        """
+        return self.session_var.get()
+
+    def reset_context(self):
+        """Reset the session context."""
+        token = self.get_context()
+        if token is not None:
+            self.session_var.reset(token)
+
+    def stop_cleanup(self):
+        """
+        Stop the cleanup thread.
+        Useful for graceful shutdown of the application.
+        """
+        self._stop_event.set()
+        if self._cleanup_thread:
+            self._cleanup_thread.join()
+
+    def __del__(self):
+        """
+        Ensure cleanup thread is stopped when the object is deleted.
+        """
+        self.stop_cleanup()
+
+
+context_store = ContextStore()

hypern/database/sqlalchemy/__init__.py

@@ -0,0 +1,4 @@
+from .repository import Model, PostgresRepository
+from .config import SqlalchemyConfig
+
+__all__ = ["Model", "PostgresRepository", "SqlalchemyConfig"]