simple-dep-cache 0.1.1__py3-none-any.whl

simple_dep_cache/__init__.py

@@ -0,0 +1,19 @@
+from .context import add_dependency, current_cache_key
+from .decorators import async_cache_with_deps, cache_with_deps
+from .events import CacheEvent, CacheEventType, StatsCollector, create_logger_callback
+from .manager import AsyncCacheManager, CacheManager
+from .types import CacheValue
+
+__all__ = [
+    "CacheManager",
+    "AsyncCacheManager",
+    "cache_with_deps",
+    "async_cache_with_deps",
+    "add_dependency",
+    "current_cache_key",
+    "CacheValue",
+    "CacheEvent",
+    "CacheEventType",
+    "StatsCollector",
+    "create_logger_callback",
+]

simple_dep_cache/config.py

@@ -0,0 +1,190 @@
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import redis
+    import redis.asyncio
+
+
+def _str_to_bool(value: str | bool) -> bool:
+    """Convert string environment variable to boolean."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        if value.lower() in ("true", "1", "yes", "on"):
+            return True
+    return False
+
+
+def _str_to_int(value: str, default: int) -> int:
+    """Convert string environment variable to integer."""
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return default
+
+
+class Config:
+    """Configuration settings for simple_dep_cache."""
+
+    @property
+    def cache_enabled(self) -> bool:
+        """Whether caching is enabled. Can be disabled with DEP_CACHE_ENABLED=false."""
+        return _str_to_bool(os.getenv("DEP_CACHE_ENABLED", "true"))
+
+    @property
+    def callback_error_silent(self) -> bool:
+        """Whether to silently ignore callback errors or print traceback.
+
+        Set DEP_CACHE_CALLBACK_SILENT=false to print tracebacks.
+        """
+        return _str_to_bool(os.getenv("DEP_CACHE_CALLBACK_SILENT", "true"))
+
+    @property
+    def redis_url(self) -> str | None:
+        """Redis connection URL. Takes precedence over host/port/db settings.
+
+        Example: redis://localhost:6379/0 or redis://user:pass@host:port/db
+        Environment variable: REDIS_URL
+        """
+        return os.getenv("REDIS_URL")
+
+    @property
+    def redis_host(self) -> str:
+        """Redis host. Default: localhost
+        Environment variable: REDIS_HOST
+        """
+        return os.getenv("REDIS_HOST", "localhost")
+
+    @property
+    def redis_port(self) -> int:
+        """Redis port. Default: 6379
+        Environment variable: REDIS_PORT
+        """
+        return _str_to_int(os.getenv("REDIS_PORT", "6379"), 6379)
+
+    @property
+    def redis_db(self) -> int:
+        """Redis database number. Default: 0
+        Environment variable: REDIS_DB
+        """
+        return _str_to_int(os.getenv("REDIS_DB", "0"), 0)
+
+    @property
+    def redis_password(self) -> str | None:
+        """Redis password. Default: None
+        Environment variable: REDIS_PASSWORD
+        """
+        return os.getenv("REDIS_PASSWORD")
+
+    @property
+    def redis_username(self) -> str | None:
+        """Redis username (for Redis 6+). Default: None
+        Environment variable: REDIS_USERNAME
+        """
+        return os.getenv("REDIS_USERNAME")
+
+    @property
+    def redis_ssl(self) -> bool:
+        """Whether to use SSL/TLS for Redis connection. Default: False
+        Environment variable: REDIS_SSL
+        """
+        return _str_to_bool(os.getenv("REDIS_SSL", "false"))
+
+    @property
+    def redis_socket_timeout(self) -> float | None:
+        """Redis socket timeout in seconds. Default: None
+        Environment variable: REDIS_SOCKET_TIMEOUT
+        """
+        timeout_str = os.getenv("REDIS_SOCKET_TIMEOUT")
+        if timeout_str:
+            try:
+                return float(timeout_str)
+            except (ValueError, TypeError):
+                pass
+        return None
+
+    @property
+    def redis_connection_pool_max_connections(self) -> int:
+        """Maximum connections in Redis connection pool. Default: 50
+        Environment variable: REDIS_MAX_CONNECTIONS
+        """
+        return _str_to_int(os.getenv("REDIS_MAX_CONNECTIONS", "50"), 50)
+
+
+def create_redis_client_from_config(
+    config_instance: Config | None = None,
+) -> "redis.Redis":
+    """Create a Redis client from configuration settings."""
+    import redis
+
+    cfg = config_instance or config
+
+    if cfg.redis_url:
+        return redis.Redis.from_url(
+            cfg.redis_url,
+            decode_responses=True,
+            socket_timeout=cfg.redis_socket_timeout,
+            max_connections=cfg.redis_connection_pool_max_connections,
+        )
+
+    connection_kwargs = {
+        "host": cfg.redis_host,
+        "port": cfg.redis_port,
+        "db": cfg.redis_db,
+        "decode_responses": True,
+        "ssl": cfg.redis_ssl,
+        "max_connections": cfg.redis_connection_pool_max_connections,
+    }
+
+    if cfg.redis_password:
+        connection_kwargs["password"] = cfg.redis_password
+
+    if cfg.redis_username:
+        connection_kwargs["username"] = cfg.redis_username
+
+    if cfg.redis_socket_timeout:
+        connection_kwargs["socket_timeout"] = cfg.redis_socket_timeout
+
+    return redis.Redis(**connection_kwargs)
+
+
+def create_async_redis_client_from_config(
+    config_instance: Config | None = None,
+) -> "redis.asyncio.Redis":
+    """Create an async Redis client from configuration settings."""
+    import redis.asyncio as async_redis
+
+    cfg = config_instance or config
+
+    if cfg.redis_url:
+        return async_redis.Redis.from_url(
+            cfg.redis_url,
+            decode_responses=True,
+            socket_timeout=cfg.redis_socket_timeout,
+            max_connections=cfg.redis_connection_pool_max_connections,
+        )
+
+    connection_kwargs = {
+        "host": cfg.redis_host,
+        "port": cfg.redis_port,
+        "db": cfg.redis_db,
+        "decode_responses": True,
+        "ssl": cfg.redis_ssl,
+        "max_connections": cfg.redis_connection_pool_max_connections,
+    }
+
+    if cfg.redis_password:
+        connection_kwargs["password"] = cfg.redis_password
+
+    if cfg.redis_username:
+        connection_kwargs["username"] = cfg.redis_username
+
+    if cfg.redis_socket_timeout:
+        connection_kwargs["socket_timeout"] = cfg.redis_socket_timeout
+
+    return async_redis.Redis(**connection_kwargs)
+
+
+# Global config instance
+config = Config()

simple_dep_cache/context.py

@@ -0,0 +1,38 @@
+from contextvars import ContextVar
+
+_current_cache_key: ContextVar[str | None] = ContextVar("current_cache_key", default=None)
+_current_dependencies: ContextVar[None | set[str]] = ContextVar(
+    "current_dependencies", default=None
+)
+
+
+def set_current_cache_key(key: str) -> None:
+    """Set the current cache key in context."""
+    _current_cache_key.set(key)
+
+
+def current_cache_key() -> str | None:
+    """Get the current cache key from context."""
+    return _current_cache_key.get()
+
+
+def add_dependency(dependency: str) -> None:
+    """Add a dependency to the current cache context."""
+    deps = (_current_dependencies.get() or set()).copy()
+    deps.add(dependency)
+    _current_dependencies.set(deps)
+
+
+def get_current_dependencies() -> set[str]:
+    """Get all dependencies for the current cache context."""
+    return (_current_dependencies.get() or set()).copy()
+
+
+def clear_current_dependencies() -> None:
+    """Clear all dependencies in the current context."""
+    _current_dependencies.set(set())
+
+
+def set_current_dependencies(dependencies: set[str]) -> None:
+    """Set the current dependencies."""
+    _current_dependencies.set(dependencies)

simple_dep_cache/decorators.py

@@ -0,0 +1,193 @@
+import asyncio
+import hashlib
+from collections.abc import Callable
+from functools import wraps
+
+from .config import config
+from .context import (
+    clear_current_dependencies,
+    get_current_dependencies,
+    set_current_cache_key,
+    set_current_dependencies,
+)
+from .manager import AsyncCacheManager, CacheManager
+
+
+def _generate_cache_key(func: Callable, args: tuple, kwargs: dict) -> str:
+    """Generate a cache key based on function name and arguments."""
+    func_name = f"{func.__module__}.{func.__qualname__}"
+
+    # Create a stable string representation of arguments
+    arg_parts = []
+
+    # Add positional args
+    for arg in args:
+        arg_parts.append(str(arg))
+
+    # Add keyword args (sorted for consistency)
+    for key in sorted(kwargs.keys()):
+        arg_parts.append(f"{key}={kwargs[key]}")
+
+    args_str = ",".join(arg_parts)
+    full_key = f"{func_name}({args_str})"
+
+    # Hash for consistent length and avoid special characters
+    return hashlib.md5(full_key.encode()).hexdigest()
+
+
+def cache_with_deps(
+    *,
+    cache_manager: CacheManager | None = None,
+    ttl: int | None = None,
+    key_prefix: str | None = None,
+    dependencies: set | None = None,
+) -> Callable:
+    """
+    Decorator for caching function results with dependency tracking.
+
+    Args:
+        cache_manager: The cache manager instance to use (optional)
+        ttl: Time to live in seconds (optional)
+        key_prefix: Custom prefix for cache keys (optional)
+        dependencies: Additional dependencies to track (optional)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # If caching is disabled, just execute the function
+            if not config.cache_enabled:
+                return func(*args, **kwargs)
+
+            # Use provided cache manager or create default one
+            active_cache_manager = cache_manager or CacheManager()
+
+            # Generate cache key
+            cache_key = _generate_cache_key(func, args, kwargs)
+            if key_prefix:
+                cache_key = f"{key_prefix}:{cache_key}"
+
+            # Check cache first
+            cached_result = active_cache_manager.get(cache_key)
+            if cached_result is not None:
+                return cached_result
+
+            # Set up context for dependency tracking
+            old_dependencies = get_current_dependencies()
+            clear_current_dependencies()
+            set_current_cache_key(cache_key)
+
+            try:
+                # Execute function
+                result = func(*args, **kwargs)
+
+                # Get dependencies collected during execution
+                collected_dependencies = get_current_dependencies()
+
+                # Combine collected dependencies with additional dependencies
+                all_dependencies = set()
+                if collected_dependencies:
+                    all_dependencies.update(collected_dependencies)
+                if dependencies:
+                    all_dependencies.update(dependencies)
+
+                # Cache the result with dependencies
+                active_cache_manager.set(
+                    cache_key,
+                    result,
+                    ttl,
+                    all_dependencies if all_dependencies else None,
+                )
+
+                return result
+
+            finally:
+                # Restore previous context
+                set_current_dependencies(old_dependencies)
+                set_current_cache_key(None)
+
+        return wrapper
+
+    return decorator
+
+
+def async_cache_with_deps(
+    *,
+    cache_manager: AsyncCacheManager | None = None,
+    ttl: int | None = None,
+    key_prefix: str | None = None,
+    dependencies: set | None = None,
+) -> Callable:
+    """
+    Async decorator for caching function results with dependency tracking.
+
+    Args:
+        cache_manager: The async cache manager instance to use (optional)
+        ttl: Time to live in seconds (optional)
+        key_prefix: Custom prefix for cache keys (optional)
+        dependencies: Additional dependencies to track (optional)
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            # If caching is disabled, just execute the function
+            if not config.cache_enabled:
+                if asyncio.iscoroutinefunction(func):
+                    return await func(*args, **kwargs)
+                else:
+                    return func(*args, **kwargs)
+
+            # Use provided cache manager or create default one
+            active_cache_manager = cache_manager or AsyncCacheManager()
+
+            # Generate cache key
+            cache_key = _generate_cache_key(func, args, kwargs)
+            if key_prefix:
+                cache_key = f"{key_prefix}:{cache_key}"
+
+            # Check cache first
+            cached_result = await active_cache_manager.get(cache_key)
+            if cached_result is not None:
+                return cached_result
+
+            # Set up context for dependency tracking
+            old_dependencies = get_current_dependencies()
+            clear_current_dependencies()
+            set_current_cache_key(cache_key)
+
+            try:
+                # Execute function
+                if asyncio.iscoroutinefunction(func):
+                    result = await func(*args, **kwargs)
+                else:
+                    result = func(*args, **kwargs)
+
+                # Get dependencies collected during execution
+                collected_dependencies = get_current_dependencies()
+
+                # Combine collected dependencies with additional dependencies
+                all_dependencies = set()
+                if collected_dependencies:
+                    all_dependencies.update(collected_dependencies)
+                if dependencies:
+                    all_dependencies.update(dependencies)
+
+                # Cache the result with dependencies
+                await active_cache_manager.set(
+                    cache_key,
+                    result,
+                    ttl,
+                    all_dependencies if all_dependencies else None,
+                )
+
+                return result
+
+            finally:
+                # Restore previous context
+                set_current_dependencies(old_dependencies)
+                set_current_cache_key(None)
+
+        return wrapper
+
+    return decorator

simple_dep_cache/events.py

@@ -0,0 +1,166 @@
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from .config import config
+
+logger = logging.getLogger(__name__)
+
+
+class CacheEventType(Enum):
+    """Types of cache events."""
+
+    HIT = "hit"
+    MISS = "miss"
+    SET = "set"
+    DELETE = "delete"
+    INVALIDATE = "invalidate"
+    CLEAR = "clear"
+
+
+@dataclass
+class CacheEvent:
+    """Cache event data."""
+
+    event_type: CacheEventType
+    key: str
+    timestamp: float
+    value: Any = None
+    dependencies: set[str] | None = None
+    ttl: int | None = None
+    count: int | None = None  # For bulk operations
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = time.time()
+
+
+class EventEmitter:
+    """Simple event emitter for cache events."""
+
+    def __init__(self):
+        self._callbacks: dict[CacheEventType, list[Callable]] = {
+            event_type: [] for event_type in CacheEventType
+        }
+        self._global_callbacks: list[Callable] = []
+
+    def on(self, event_type: CacheEventType, callback: Callable[[CacheEvent], None]) -> None:
+        """Register a callback for a specific event type."""
+        self._callbacks[event_type].append(callback)
+
+    def on_all(self, callback: Callable[[CacheEvent], None]) -> None:
+        """Register a callback for all event types."""
+        self._global_callbacks.append(callback)
+
+    def off(self, event_type: CacheEventType, callback: Callable[[CacheEvent], None]) -> bool:
+        """Unregister a callback for a specific event type."""
+        if callback in self._callbacks[event_type]:
+            self._callbacks[event_type].remove(callback)
+            return True
+        return False
+
+    def off_all(self, callback: Callable[[CacheEvent], None]) -> bool:
+        """Unregister a callback from all events."""
+        if callback in self._global_callbacks:
+            self._global_callbacks.remove(callback)
+            return True
+        return False
+
+    def emit(self, event: CacheEvent) -> None:
+        """Emit an event to all registered callbacks."""
+        # Call specific event callbacks
+        for callback in self._callbacks[event.event_type]:
+            try:
+                callback(event)
+            except Exception as e:
+                if not config.callback_error_silent:
+                    logger.exception("Error in cache event callback: %s", e)
+
+        # Call global callbacks
+        for callback in self._global_callbacks:
+            try:
+                callback(event)
+            except Exception as e:
+                if not config.callback_error_silent:
+                    logger.exception("Error in cache event callback: %s", e)
+
+    def clear_all(self) -> None:
+        """Clear all callbacks."""
+        for event_type in CacheEventType:
+            self._callbacks[event_type].clear()
+        self._global_callbacks.clear()
+
+
+# Pre-built callback functions for common use cases
+class StatsCollector:
+    """Collect cache statistics."""
+
+    def __init__(self):
+        self.stats = {
+            "hits": 0,
+            "misses": 0,
+            "sets": 0,
+            "deletes": 0,
+            "invalidations": 0,
+            "clears": 0,
+        }
+        self.start_time = time.time()
+
+    def __call__(self, event: CacheEvent) -> None:
+        """Callback to collect stats."""
+        if event.event_type == CacheEventType.HIT:
+            self.stats["hits"] += 1
+        elif event.event_type == CacheEventType.MISS:
+            self.stats["misses"] += 1
+        elif event.event_type == CacheEventType.SET:
+            self.stats["sets"] += 1
+        elif event.event_type == CacheEventType.DELETE:
+            self.stats["deletes"] += event.count or 1
+        elif event.event_type == CacheEventType.INVALIDATE:
+            self.stats["invalidations"] += event.count or 1
+        elif event.event_type == CacheEventType.CLEAR:
+            self.stats["clears"] += event.count or 1
+
+    def get_hit_ratio(self) -> float:
+        """Get cache hit ratio."""
+        total = self.stats["hits"] + self.stats["misses"]
+        return self.stats["hits"] / total if total > 0 else 0.0
+
+    def get_stats(self) -> dict:
+        """Get all stats with additional computed metrics."""
+        runtime = time.time() - self.start_time
+        return {
+            **self.stats,
+            "hit_ratio": self.get_hit_ratio(),
+            "total_operations": sum(self.stats.values()),
+            "runtime_seconds": runtime,
+            "ops_per_second": sum(self.stats.values()) / runtime if runtime > 0 else 0,
+        }
+
+    def reset(self) -> None:
+        """Reset all statistics."""
+        for key in self.stats:
+            self.stats[key] = 0
+        self.start_time = time.time()
+
+
+def create_logger_callback(name: str = "cache") -> Callable[[CacheEvent], None]:
+    """Create a callback that logs cache events."""
+
+    def logger_callback(event: CacheEvent) -> None:
+        if event.event_type in (CacheEventType.HIT, CacheEventType.MISS):
+            print(f"[{name}] {event.event_type.value.upper()}: {event.key}")
+        elif event.event_type == CacheEventType.SET:
+            deps_str = f" deps={list(event.dependencies)}" if event.dependencies else ""
+            ttl_str = f" ttl={event.ttl}s" if event.ttl else ""
+            print(f"[{name}] SET: {event.key}{deps_str}{ttl_str}")
+        elif event.event_type == CacheEventType.INVALIDATE:
+            print(f"[{name}] INVALIDATE: {event.key} (cleared {event.count} entries)")
+        elif event.event_type in (CacheEventType.DELETE, CacheEventType.CLEAR):
+            count_str = f" ({event.count} entries)" if event.count else ""
+            print(f"[{name}] {event.event_type.value.upper()}: {event.key}{count_str}")
+
+    return logger_callback

simple_dep_cache/manager.py

@@ -0,0 +1,341 @@
+import logging
+import time
+
+import redis
+import redis.asyncio as async_redis
+
+from .config import (
+    create_async_redis_client_from_config,
+    create_redis_client_from_config,
+)
+from .events import CacheEvent, CacheEventType, EventEmitter
+from .types import CacheValue, deserialize_value, serialize_value
+
+logger = logging.getLogger(__name__)
+
+
+class CacheManager:
+    """Synchronous Redis-based cache manager with dependency tracking."""
+
+    def __init__(self, redis_client: redis.Redis | None = None, prefix: str = "cache"):
+        if redis_client is None:
+            from .config import config
+
+            self._redis = None
+            if config.cache_enabled:
+                logger.info(
+                    "Creating Redis client from environment configuration. "
+                    "Provide a custom redis_client parameter to override."
+                )
+                self._redis = create_redis_client_from_config()
+        else:
+            self._redis = redis_client
+        self.prefix = prefix
+        self.events = EventEmitter()
+
+    @property
+    def redis(self) -> redis.Redis:
+        """Get the Redis client, raising an error if not configured."""
+        if self._redis is None:
+            raise RuntimeError("Cache is disabled or redis client is not configured.")
+        return self._redis
+
+    def _cache_key(self, key: str) -> str:
+        """Generate prefixed cache key."""
+        return f"{self.prefix}:{key}"
+
+    def _deps_key(self, dependency: str) -> str:
+        """Generate dependency tracking key."""
+        return f"{self.prefix}:deps:{dependency}"
+
+    def set(
+        self,
+        key: str,
+        value: CacheValue,
+        ttl: int | None = None,
+        dependencies: set[str] | None = None,
+    ) -> None:
+        """Set a cache value with optional TTL and dependencies."""
+        cache_key = self._cache_key(key)
+        serialized_value = serialize_value(value)
+
+        if ttl:
+            self.redis.setex(cache_key, ttl, serialized_value)
+        else:
+            self.redis.set(cache_key, serialized_value)
+
+        if dependencies:
+            for dep in dependencies:
+                dep_key = self._deps_key(dep)
+                self.redis.sadd(dep_key, cache_key)
+                if ttl:
+                    current_ttl = self.redis.ttl(dep_key)
+                    # Ensure dependency tracking key lives at least as long as cache entries
+                    # current_ttl: -1 = no expiration, -2 = doesn't exist, >0 = remaining seconds
+                    # Set/extend TTL if: key is persistent OR key has shorter TTL than ours
+                    if current_ttl == -1 or (current_ttl != -2 and current_ttl < ttl):
+                        self.redis.expire(dep_key, ttl)
+
+        # Emit set event
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.SET,
+                key=key,
+                timestamp=time.time(),
+                value=value,
+                dependencies=dependencies,
+                ttl=ttl,
+            )
+        )
+
+    def get(self, key: str) -> CacheValue | None:
+        """Get a cache value."""
+        cache_key = self._cache_key(key)
+        value = self.redis.get(cache_key)
+
+        if value is None:
+            # Emit cache miss event
+            self.events.emit(
+                CacheEvent(event_type=CacheEventType.MISS, key=key, timestamp=time.time())
+            )
+            return None
+
+        # Emit cache hit event
+        deserialized_value = deserialize_value(value)
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.HIT,
+                key=key,
+                timestamp=time.time(),
+                value=deserialized_value,
+            )
+        )
+        return deserialized_value
+
+    def delete(self, *keys: str) -> int:
+        """Delete cache entries."""
+        cache_keys = [self._cache_key(key) for key in keys]
+        count = self.redis.delete(*cache_keys) if cache_keys else 0
+
+        # Emit delete event for each key
+        for key in keys:
+            self.events.emit(
+                CacheEvent(
+                    event_type=CacheEventType.DELETE,
+                    key=key,
+                    timestamp=time.time(),
+                    count=1,
+                )
+            )
+
+        return count
+
+    def clear(self, pattern: str = "*") -> int:
+        """Clear cache entries matching pattern."""
+        pattern_key = self._cache_key(pattern)
+        keys = list(self.redis.scan_iter(match=pattern_key))
+        count = self.redis.delete(*keys) if keys else 0
+
+        # Emit clear event
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.CLEAR,
+                key=pattern,
+                timestamp=time.time(),
+                count=count,
+            )
+        )
+
+        return count
+
+    def invalidate_dependency(self, dependency: str) -> int:
+        """Invalidate all cache entries that depend on the given dependency."""
+        dep_key = self._deps_key(dependency)
+        cache_keys = self.redis.smembers(dep_key)
+
+        if not cache_keys:
+            count = 0
+        else:
+            count = self.redis.delete(*cache_keys)
+            self.redis.delete(dep_key)
+
+        # Emit invalidate event
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.INVALIDATE,
+                key=dependency,
+                timestamp=time.time(),
+                count=count,
+            )
+        )
+
+        return count
+
+    def exists(self, key: str) -> bool:
+        """Check if a cache key exists."""
+        return bool(self.redis.exists(self._cache_key(key)))
+
+    def ttl(self, key: str) -> int:
+        """Get TTL for a cache key."""
+        return self.redis.ttl(self._cache_key(key))
+
+
+class AsyncCacheManager:
+    """Asynchronous Redis-based cache manager with dependency tracking."""
+
+    def __init__(self, redis_client: async_redis.Redis | None = None, prefix: str = "cache"):
+        if redis_client is None:
+            logger.info(
+                "Creating async Redis client from environment configuration. "
+                "Provide a custom redis_client parameter to override."
+            )
+            self.redis = create_async_redis_client_from_config()
+        else:
+            self.redis = redis_client
+        self.prefix = prefix
+        self.events = EventEmitter()
+
+    def _cache_key(self, key: str) -> str:
+        """Generate prefixed cache key."""
+        return f"{self.prefix}:{key}"
+
+    def _deps_key(self, dependency: str) -> str:
+        """Generate dependency tracking key."""
+        return f"{self.prefix}:deps:{dependency}"
+
+    async def set(
+        self,
+        key: str,
+        value: CacheValue,
+        ttl: int | None = None,
+        dependencies: set[str] | None = None,
+    ) -> None:
+        """Set a cache value with optional TTL and dependencies."""
+        cache_key = self._cache_key(key)
+        serialized_value = serialize_value(value)
+
+        if ttl:
+            await self.redis.setex(cache_key, ttl, serialized_value)
+        else:
+            await self.redis.set(cache_key, serialized_value)
+
+        if dependencies:
+            for dep in dependencies:
+                dep_key = self._deps_key(dep)
+                await self.redis.sadd(dep_key, cache_key)
+                if ttl:
+                    current_ttl = await self.redis.ttl(dep_key)
+                    # Ensure dependency tracking key lives at least as long as cache entries
+                    # current_ttl: -1 = no expiration, -2 = doesn't exist, >0 = remaining seconds
+                    # Set/extend TTL if: key is persistent OR key has shorter TTL than ours
+                    if current_ttl == -1 or (current_ttl != -2 and current_ttl < ttl):
+                        await self.redis.expire(dep_key, ttl)
+
+        # Emit set event
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.SET,
+                key=key,
+                timestamp=time.time(),
+                value=value,
+                dependencies=dependencies,
+                ttl=ttl,
+            )
+        )
+
+    async def get(self, key: str) -> CacheValue | None:
+        """Get a cache value."""
+        cache_key = self._cache_key(key)
+        value = await self.redis.get(cache_key)
+
+        if value is None:
+            # Emit cache miss event
+            self.events.emit(
+                CacheEvent(event_type=CacheEventType.MISS, key=key, timestamp=time.time())
+            )
+            return None
+
+        # Emit cache hit event
+        deserialized_value = deserialize_value(value)
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.HIT,
+                key=key,
+                timestamp=time.time(),
+                value=deserialized_value,
+            )
+        )
+        return deserialized_value
+
+    async def delete(self, *keys: str) -> int:
+        """Delete cache entries."""
+        cache_keys = [self._cache_key(key) for key in keys]
+        count = await self.redis.delete(*cache_keys) if cache_keys else 0
+
+        # Emit delete event for each key
+        for key in keys:
+            self.events.emit(
+                CacheEvent(
+                    event_type=CacheEventType.DELETE,
+                    key=key,
+                    timestamp=time.time(),
+                    count=1,
+                )
+            )
+
+        return count
+
+    async def clear(self, pattern: str = "*") -> int:
+        """Clear cache entries matching pattern."""
+        pattern_key = self._cache_key(pattern)
+        keys = []
+        async for key in self.redis.scan_iter(match=pattern_key):
+            keys.append(key)
+        count = await self.redis.delete(*keys) if keys else 0
+
+        # Emit clear event
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.CLEAR,
+                key=pattern,
+                timestamp=time.time(),
+                count=count,
+            )
+        )
+
+        return count
+
+    async def invalidate_dependency(self, dependency: str) -> int:
+        """Invalidate all cache entries that depend on the given dependency."""
+        dep_key = self._deps_key(dependency)
+        cache_keys = await self.redis.smembers(dep_key)
+
+        if not cache_keys:
+            count = 0
+        else:
+            count = await self.redis.delete(*cache_keys)
+            await self.redis.delete(dep_key)
+
+        # Emit invalidate event
+        self.events.emit(
+            CacheEvent(
+                event_type=CacheEventType.INVALIDATE,
+                key=dependency,
+                timestamp=time.time(),
+                count=count,
+            )
+        )
+
+        return count
+
+    async def exists(self, key: str) -> bool:
+        """Check if a cache key exists."""
+        return bool(await self.redis.exists(self._cache_key(key)))
+
+    async def ttl(self, key: str) -> int:
+        """Get TTL for a cache key."""
+        return await self.redis.ttl(self._cache_key(key))
+
+    async def close(self) -> None:
+        """Close the Redis connection."""
+        await self.redis.aclose()

simple_dep_cache/types.py

@@ -0,0 +1,34 @@
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import orjson
+
+try:
+    import orjson
+
+    HAS_ORJSON = True
+except ImportError:
+    HAS_ORJSON = False
+
+CacheValue = str | int | float | bool | dict | list | None
+
+
+def serialize_value(value: CacheValue) -> str:
+    """Serialize a cache value to string for Redis storage."""
+    if isinstance(value, str):
+        return value
+    if HAS_ORJSON:
+        return orjson.dumps(value).decode("utf-8")
+    return json.dumps(value)
+
+
+def deserialize_value(value: str) -> CacheValue:
+    """Deserialize a string value from Redis back to Python object."""
+    JSONDecodeError = orjson.JSONDecodeError if HAS_ORJSON else json.JSONDecodeError
+    try:
+        if HAS_ORJSON:
+            return orjson.loads(value)
+        return json.loads(value)
+    except JSONDecodeError:
+        return value

simple_dep_cache-0.1.1.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: simple-dep-cache
+Version: 0.1.1
+Summary: Redis-based caching library with intelligent dependency tracking for Python applications
+License: MIT
+Keywords: cache,cache invalidation,dependency,redis
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: redis
+Provides-Extra: fast-json
+Requires-Dist: orjson; extra == 'fast-json'
+Description-Content-Type: text/markdown
+
+# simple-dep-cache
+
+A Redis-based caching library with dependency tracking for Python applications.
+
+## Overview
+
+Cache function results and automatically invalidate related caches when dependencies change. Uses Redis for distributed caching and supports both sync/async functions.
+
+## Installation
+
+```bash
+pip install simple-dep-cache
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from simple_dep_cache import cache_with_deps, add_dependency, CacheManager
+
+# Initialize cache manager (optional - will be created automatically if not provided)
+cache = CacheManager()
+
+@cache_with_deps(cache_manager=cache, ttl=300)
+def get_user_profile(user_id):
+    # This function's result depends on user data
+    add_dependency(f"user:{user_id}")
+
+    # Expensive operation (e.g., database query, API call)
+    return fetch_user_from_database(user_id)
+
+@cache_with_deps(ttl=600)  # No cache_manager - will create one automatically
+def get_user_posts(user_id):
+    # This depends on both user and posts data
+    add_dependency(f"user:{user_id}")
+    add_dependency(f"posts:user:{user_id}")
+
+    return fetch_user_posts_from_database(user_id)
+
+# Use the cached functions
+profile = get_user_profile("123")  # Cache miss - fetches from DB
+profile = get_user_profile("123")  # Cache hit - returns cached result
+
+posts = get_user_posts("123")     # Cache miss - fetches from DB
+posts = get_user_posts("123")     # Cache hit - returns cached result
+
+# When user data changes, invalidate the dependency
+cache.invalidate_dependency("user:123")
+# Now both get_user_profile("123") and get_user_posts("123") are invalidated!
+
+profile = get_user_profile("123")  # Cache miss - will fetch fresh data
+```
+
+### Async Support
+
+```python
+from simple_dep_cache import async_cache_with_deps, add_dependency, AsyncCacheManager
+
+cache = AsyncCacheManager()
+
+@async_cache_with_deps(cache_manager=cache, ttl=300)
+async def get_user_profile_async(user_id):
+    add_dependency(f"user:{user_id}")
+    return await fetch_user_from_database_async(user_id)
+
+# Usage
+profile = await get_user_profile_async("123")  # Cache miss
+profile = await get_user_profile_async("123")  # Cache hit
+
+# Invalidate dependency
+await cache.invalidate_dependency("user:123")
+```
+
+### Monitoring
+
+```python
+from simple_dep_cache import StatsCollector, create_logger_callback
+
+cache = CacheManager()
+stats = StatsCollector()
+cache.events.on_all(stats)
+cache.events.on_all(create_logger_callback("my_cache"))
+
+# Check statistics
+print(stats.get_stats())  # hit_ratio, ops_per_second, etc.
+```
+
+## Configuration
+
+```bash
+REDIS_URL=redis://localhost:6379/0    # Full Redis URL (preferred)
+REDIS_HOST=localhost                  # Or individual settings
+REDIS_PORT=6379
+REDIS_PASSWORD=secret
+DEP_CACHE_ENABLED=true                # Disable caching entirely
+```
+
+## Manual Cache Operations
+
+```python
+cache = CacheManager()
+
+# Direct operations
+cache.set("key", value, ttl=300, dependencies={"dep1"})
+value = cache.get("key")
+cache.delete("key")
+cache.invalidate_dependency("dep1")  # Invalidates all dependent caches
+```
+
+## API Reference
+
+**Decorators:**
+
+- `@cache_with_deps(cache_manager, ttl, key_prefix, dependencies)`
+- `@async_cache_with_deps(cache_manager, ttl, key_prefix, dependencies)`
+
+If `cache_manager` is not provided, one will be created automatically using configured environment variables or defaults.
+
+**Context:**
+
+- `add_dependency(dependency)` - Track dependency in current function
+- `current_cache_key()` - Get current cache key
+
+**Managers:**
+
+- `CacheManager(redis_client, prefix)` - Sync Redis cache manager
+- `AsyncCacheManager(redis_client, prefix)` - Async Redis cache manager
+
+**Monitoring:**
+
+- `StatsCollector()` - Cache statistics
+
+## Requirements
+
+- Python 3.10+
+- Redis server
+- `redis` package
+
+## License
+
+MIT

simple_dep_cache-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+simple_dep_cache/__init__.py,sha256=IFHKaQii5mF9hnYGkNRhNrCNwvxVW5cUkFyzhdIOTL0,557
+simple_dep_cache/config.py,sha256=ebl_Fwj07RrDPPPfgWym6w8xZ3wI9OPhtSzBT3B9AlU,5612
+simple_dep_cache/context.py,sha256=F6eaO01rQNAARq1r5H_LrXhJ9AJe8CysH21vx_Dok-w,1162
+simple_dep_cache/decorators.py,sha256=Hu87FrvPKrjn-o8xGCO8yUpTq-WXuwdR2mP6jjkdsf0,6406
+simple_dep_cache/events.py,sha256=5iLaulgO7c-x2Nafgn41Y1uCPuRSQv4JE0oQKND8EdM,5812
+simple_dep_cache/manager.py,sha256=j_pgZQsvSbIvasCppRGBxdQb0iD6mr76YHQcn3fj19k,11176
+simple_dep_cache/types.py,sha256=Kxu0k8rfVkK7kxIvEQG7NI7SQSgAiFnxPEfrHj5nRtk,855
+simple_dep_cache-0.1.1.dist-info/METADATA,sha256=DwOWPen-TITVTrudO-9p6NDz5BJKQIAFk-7DT_TuLxs,4530
+simple_dep_cache-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+simple_dep_cache-0.1.1.dist-info/RECORD,,

simple_dep_cache-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any