cachu 0.1.1__py3-none-any.whl

cachu/config.py

@@ -0,0 +1,193 @@
+"""Configuration module for cache backends with package isolation.
+
+Each calling library gets its own isolated configuration, preventing
+configuration conflicts when multiple libraries use the cachu package.
+"""
+import logging
+import os
+import pathlib
+import sys
+from dataclasses import asdict, dataclass, replace
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_disabled: bool = False
+
+
+def disable() -> None:
+    """Disable all caching globally.
+    """
+    global _disabled
+    _disabled = True
+
+
+def enable() -> None:
+    """Re-enable caching after disable().
+    """
+    global _disabled
+    _disabled = False
+
+
+def is_disabled() -> bool:
+    """Check if caching is globally disabled.
+    """
+    return _disabled
+
+
+def _get_caller_package() -> str | None:
+    """Get the top-level package name of the caller.
+    """
+    frame = sys._getframe(1)
+    while frame:
+        name = frame.f_globals.get('__name__', '')
+        if name and not name.startswith('cachu'):
+            pkg = name.split('.')[0]
+            if pkg == '__main__' and sys.argv and sys.argv[0]:
+                return f'__main__.{pathlib.Path(sys.argv[0]).stem}'
+            return pkg
+        frame = frame.f_back
+    return None
+
+
+@dataclass
+class CacheConfig:
+    """Configuration for cache backends.
+    """
+    backend: str = 'memory'
+    key_prefix: str = ''
+    file_dir: str = '/tmp'
+    redis_url: str = 'redis://localhost:6379/0'
+    redis_distributed: bool = False
+
+
+class ConfigRegistry:
+    """Registry that maintains per-package cache configurations.
+
+    Each library (identified by top-level package name) gets its own
+    isolated configuration. This prevents configuration conflicts when
+    multiple libraries use the cache package with different settings.
+    """
+
+    def __init__(self) -> None:
+        self._configs: dict[str | None, CacheConfig] = {}
+        self._default = CacheConfig()
+
+    def configure(
+        self,
+        package: str | None = None,
+        backend: str | None = None,
+        key_prefix: str | None = None,
+        file_dir: str | None = None,
+        redis_url: str | None = None,
+        redis_distributed: bool | None = None,
+    ) -> CacheConfig:
+        """Configure cache for a specific package.
+        """
+        if package is None:
+            package = _get_caller_package()
+
+        updates = {
+            'backend': backend,
+            'key_prefix': key_prefix,
+            'file_dir': str(file_dir) if file_dir else None,
+            'redis_url': redis_url,
+            'redis_distributed': redis_distributed,
+        }
+        updates = {k: v for k, v in updates.items() if v is not None}
+
+        self._validate_config(updates)
+
+        if package not in self._configs:
+            self._configs[package] = replace(self._default)
+            logger.debug(f"Created new cache config for package '{package}'")
+
+        cfg = self._configs[package]
+        for key, value in updates.items():
+            setattr(cfg, key, value)
+
+        logger.debug(f"Configured cache for package '{package}': {updates}")
+        return cfg
+
+    def _validate_config(self, kwargs: dict[str, Any]) -> None:
+        """Validate configuration values.
+        """
+        if 'backend' in kwargs:
+            backend = kwargs['backend']
+            valid_backends = ('memory', 'redis', 'file')
+            if backend not in valid_backends:
+                raise ValueError(f'backend must be one of {valid_backends}, got {backend!r}')
+
+        if 'file_dir' in kwargs:
+            file_dir = kwargs['file_dir']
+            if not pathlib.Path(file_dir).is_dir():
+                raise ValueError(f'file_dir must be an existing directory, got {file_dir!r}')
+            if not os.access(file_dir, os.W_OK):
+                raise ValueError(f'file_dir must be writable, got {file_dir!r}')
+
+    def get_config(self, package: str | None = None) -> CacheConfig:
+        """Get config for a package, with fallback to default.
+        """
+        if package is None:
+            package = _get_caller_package()
+
+        if package in self._configs:
+            return self._configs[package]
+
+        return self._default
+
+    def get_all_packages(self) -> list[str | None]:
+        """Return list of configured packages.
+        """
+        return list(self._configs.keys())
+
+    def clear(self) -> None:
+        """Clear all package configurations. Primarily for testing.
+        """
+        self._configs.clear()
+
+
+_registry = ConfigRegistry()
+
+
+def configure(
+    backend: str | None = None,
+    key_prefix: str | None = None,
+    file_dir: str | None = None,
+    redis_url: str | None = None,
+    redis_distributed: bool | None = None,
+) -> CacheConfig:
+    """Configure cache settings for the caller's package.
+
+    This is the main entry point for configuration. Each calling package
+    gets its own isolated configuration.
+
+    Args:
+        backend: Default backend type ('memory', 'file', 'redis')
+        key_prefix: Prefix for all cache keys (for versioning/debugging)
+        file_dir: Directory for file-based caches
+        redis_url: Redis connection URL (e.g., 'redis://localhost:6379/0')
+        redis_distributed: Use distributed locks for Redis
+    """
+    return _registry.configure(
+        backend=backend,
+        key_prefix=key_prefix,
+        file_dir=str(file_dir) if file_dir else None,
+        redis_url=redis_url,
+        redis_distributed=redis_distributed,
+    )
+
+
+def get_config(package: str | None = None) -> CacheConfig:
+    """Get the CacheConfig for a specific package or the caller's package.
+    """
+    return _registry.get_config(package)
+
+
+def get_all_configs() -> dict[str | None, dict[str, Any]]:
+    """Return all package configurations as a dictionary.
+    """
+    result: dict[str | None, dict[str, Any]] = {'_default': asdict(_registry._default)}
+    for pkg, cfg in _registry._configs.items():
+        result[pkg] = asdict(cfg)
+    return result

cachu/decorator.py

@@ -0,0 +1,257 @@
+"""Cache decorator implementation.
+"""
+import logging
+import os
+import threading
+import time
+from functools import wraps
+from typing import Any
+from collections.abc import Callable
+
+from .backends import NO_VALUE, Backend
+from .backends.file import FileBackend
+from .backends.memory import MemoryBackend
+from .config import _get_caller_package, get_config, is_disabled
+from .keys import make_key_generator, mangle_key
+from .types import CacheEntry, CacheInfo, CacheMeta
+
+logger = logging.getLogger(__name__)
+
+_backends: dict[tuple[str | None, str, int], Backend] = {}
+_backends_lock = threading.Lock()
+
+_stats: dict[int, tuple[int, int]] = {}
+_stats_lock = threading.Lock()
+
+
+def _get_backend(package: str | None, backend_type: str, ttl: int) -> Backend:
+    """Get or create a backend instance.
+    """
+    key = (package, backend_type, ttl)
+
+    with _backends_lock:
+        if key in _backends:
+            return _backends[key]
+
+        cfg = get_config(package)
+
+        if backend_type == 'memory':
+            backend = MemoryBackend()
+        elif backend_type == 'file':
+            if ttl < 60:
+                filename = f'cache{ttl}sec'
+            elif ttl < 3600:
+                filename = f'cache{ttl // 60}min'
+            else:
+                filename = f'cache{ttl // 3600}hour'
+
+            if package:
+                filename = f'{package}_{filename}'
+
+            filepath = os.path.join(cfg.file_dir, filename)
+            backend = FileBackend(filepath)
+        elif backend_type == 'redis':
+            from .backends.redis import RedisBackend
+            backend = RedisBackend(cfg.redis_url, cfg.redis_distributed)
+        else:
+            raise ValueError(f'Unknown backend type: {backend_type}')
+
+        _backends[key] = backend
+        logger.debug(f"Created {backend_type} backend for package '{package}', {ttl}s TTL")
+        return backend
+
+
+def get_backend(backend_type: str | None = None, package: str | None = None, ttl: int = 300) -> Backend:
+    """Get a backend instance.
+
+    Args:
+        backend_type: 'memory', 'file', or 'redis'. Uses config default if None.
+        package: Package name. Auto-detected if None.
+        ttl: TTL in seconds (used for backend separation).
+    """
+    if package is None:
+        package = _get_caller_package()
+
+    if backend_type is None:
+        cfg = get_config(package)
+        backend_type = cfg.backend
+
+    return _get_backend(package, backend_type, ttl)
+
+
+def cache(
+    ttl: int = 300,
+    backend: str | None = None,
+    tag: str = '',
+    exclude: set[str] | None = None,
+    cache_if: Callable[[Any], bool] | None = None,
+    validate: Callable[[CacheEntry], bool] | None = None,
+    package: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Cache decorator with configurable backend and behavior.
+
+    Args:
+        ttl: Time-to-live in seconds (default: 300)
+        backend: Backend type ('memory', 'file', 'redis'). Uses config default if None.
+        tag: Tag for grouping related cache entries
+        exclude: Parameter names to exclude from cache key
+        cache_if: Function to determine if result should be cached.
+                  Called with result value, caches if returns True.
+        validate: Function to validate cached entries before returning.
+                  Called with CacheEntry, returns False to recompute.
+        package: Package name for config isolation. Auto-detected if None.
+
+    Per-call control via reserved kwargs (not passed to function):
+        _skip_cache: If True, bypass cache completely for this call
+        _overwrite_cache: If True, execute function and overwrite cached value
+
+    Example:
+        @cache(ttl=300, tag='users')
+        def get_user(user_id: int) -> dict:
+            return fetch_user(user_id)
+
+        # Normal call
+        user = get_user(123)
+
+        # Skip cache
+        user = get_user(123, _skip_cache=True)
+
+        # Force refresh
+        user = get_user(123, _overwrite_cache=True)
+    """
+    resolved_package = package if package is not None else _get_caller_package()
+
+    if backend is None:
+        cfg = get_config(resolved_package)
+        resolved_backend = cfg.backend
+    else:
+        resolved_backend = backend
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        key_generator = make_key_generator(fn, tag, exclude)
+
+        meta = CacheMeta(
+            ttl=ttl,
+            backend=resolved_backend,
+            tag=tag,
+            exclude=exclude or set(),
+            cache_if=cache_if,
+            validate=validate,
+            package=resolved_package,
+            key_generator=key_generator,
+        )
+
+        @wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            skip_cache = kwargs.pop('_skip_cache', False)
+            overwrite_cache = kwargs.pop('_overwrite_cache', False)
+
+            if is_disabled() or skip_cache:
+                return fn(*args, **kwargs)
+
+            backend_instance = _get_backend(resolved_package, resolved_backend, ttl)
+            cfg = get_config(resolved_package)
+
+            base_key = key_generator(*args, **kwargs)
+            cache_key = mangle_key(base_key, cfg.key_prefix, ttl)
+
+            if not overwrite_cache:
+                value, created_at = backend_instance.get_with_metadata(cache_key)
+
+                if value is not NO_VALUE:
+                    if validate is not None and created_at is not None:
+                        entry = CacheEntry(
+                            value=value,
+                            created_at=created_at,
+                            age=time.time() - created_at,
+                        )
+                        if not validate(entry):
+                            logger.debug(f'Cache validation failed for {fn.__name__}')
+                        else:
+                            _record_hit(wrapper)
+                            return value
+                    else:
+                        _record_hit(wrapper)
+                        return value
+
+            _record_miss(wrapper)
+            result = fn(*args, **kwargs)
+
+            should_cache = cache_if is None or cache_if(result)
+
+            if should_cache:
+                backend_instance.set(cache_key, result, ttl)
+                logger.debug(f'Cached {fn.__name__} with key {cache_key}')
+
+            return result
+
+        wrapper._cache_meta = meta  # type: ignore
+        wrapper._cache_key_generator = key_generator  # type: ignore
+
+        return wrapper
+
+    return decorator
+
+
+def _record_hit(fn: Callable[..., Any]) -> None:
+    """Record a cache hit for the function.
+    """
+    fn_id = id(fn)
+    with _stats_lock:
+        hits, misses = _stats.get(fn_id, (0, 0))
+        _stats[fn_id] = (hits + 1, misses)
+
+
+def _record_miss(fn: Callable[..., Any]) -> None:
+    """Record a cache miss for the function.
+    """
+    fn_id = id(fn)
+    with _stats_lock:
+        hits, misses = _stats.get(fn_id, (0, 0))
+        _stats[fn_id] = (hits, misses + 1)
+
+
+def get_cache_info(fn: Callable[..., Any]) -> CacheInfo:
+    """Get cache statistics for a decorated function.
+
+    Args:
+        fn: A function decorated with @cache
+
+    Returns
+        CacheInfo with hits, misses, and currsize
+    """
+    if hasattr(fn, '__wrapped__'):
+        actual_fn = fn
+    else:
+        actual_fn = fn
+
+    fn_id = id(actual_fn)
+
+    with _stats_lock:
+        hits, misses = _stats.get(fn_id, (0, 0))
+
+    meta = getattr(fn, '_cache_meta', None)
+    if meta is None:
+        return CacheInfo(hits=hits, misses=misses, currsize=0)
+
+    backend_instance = _get_backend(meta.package, meta.backend, meta.ttl)
+    cfg = get_config(meta.package)
+
+    fn_name = getattr(fn, '__wrapped__', fn).__name__
+    pattern = f'*:{cfg.key_prefix}{fn_name}|*'
+
+    currsize = backend_instance.count(pattern)
+
+    return CacheInfo(hits=hits, misses=misses, currsize=currsize)
+
+
+def clear_backends(package: str | None = None) -> None:
+    """Clear all backend instances for a package. Primarily for testing.
+    """
+    with _backends_lock:
+        if package is None:
+            _backends.clear()
+        else:
+            keys_to_delete = [k for k in _backends if k[0] == package]
+            for key in keys_to_delete:
+                del _backends[key]

cachu/keys.py

@@ -0,0 +1,122 @@
+"""Cache key generation and parameter filtering.
+"""
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+def _is_connection_like(obj: Any) -> bool:
+    """Check if object appears to be a database connection.
+
+    Detects SQLAlchemy connections, psycopg2, pyodbc, sqlite3, and similar.
+    """
+    if hasattr(obj, 'driver_connection'):
+        return True
+
+    if hasattr(obj, 'dialect'):
+        return True
+
+    if hasattr(obj, 'engine'):
+        return True
+
+    obj_type = str(type(obj))
+    connection_indicators = ('Connection', 'Engine', 'psycopg', 'pyodbc', 'sqlite3')
+
+    return any(indicator in obj_type for indicator in connection_indicators)
+
+
+def _normalize_tag(tag: str) -> str:
+    """Normalize tag to always be wrapped in pipes.
+    """
+    if not tag:
+        return ''
+    tag = tag.strip('|')
+    tag = tag.replace('|', '.')
+    return f'|{tag}|'
+
+
+def make_key_generator(
+    fn: Callable[..., Any],
+    tag: str = '',
+    exclude: set[str] | None = None,
+) -> Callable[..., str]:
+    """Create a key generator function for the given function.
+
+    The generated keys include:
+    - Function name
+    - Tag (if provided)
+    - All parameters except: self, cls, connections, underscore-prefixed, and excluded
+
+    Args:
+        fn: The function to generate keys for
+        tag: Optional tag for key grouping
+        exclude: Parameter names to exclude from the key
+
+    Returns
+        A function that generates cache keys from arguments
+    """
+    exclude = exclude or set()
+    unwrapped_fn = getattr(fn, '__wrapped__', fn)
+    fn_name = unwrapped_fn.__name__
+
+    if tag:
+        key_prefix = f'{fn_name}|{_normalize_tag(tag)}'
+    else:
+        key_prefix = fn_name
+
+    argspec = inspect.getfullargspec(unwrapped_fn)
+    args_reversed = list(reversed(argspec.args or []))
+    defaults_reversed = list(reversed(argspec.defaults or []))
+    args_with_defaults = {args_reversed[i]: default for i, default in enumerate(defaults_reversed)}
+
+    def generate_key(*args: Any, **kwargs: Any) -> str:
+        """Generate a cache key from function arguments.
+        """
+        positional_args = args[:len(argspec.args)]
+        varargs = args[len(argspec.args):]
+
+        as_kwargs = dict(**args_with_defaults)
+        as_kwargs.update(dict(zip(argspec.args, positional_args)))
+        as_kwargs.update({f'vararg{i+1}': varg for i, varg in enumerate(varargs)})
+        as_kwargs.update(**kwargs)
+
+        filtered = {
+            k: v for k, v in as_kwargs.items()
+            if k not in {'self', 'cls'}
+            and not k.startswith('_')
+            and k not in exclude
+            and not _is_connection_like(v)
+        }
+
+        params_str = ' '.join(f'{k}={repr(v)}' for k, v in sorted(filtered.items()))
+        return f'{key_prefix}|{params_str}'
+
+    return generate_key
+
+
+def mangle_key(key: str, key_prefix: str, ttl: int) -> str:
+    """Apply key mangling with prefix and TTL region.
+
+    Args:
+        key: The base cache key
+        key_prefix: Global key prefix from config
+        ttl: TTL in seconds (used as region identifier)
+
+    Returns
+        The mangled key
+    """
+    region = _seconds_to_region_name(ttl)
+    return f'{region}:{key_prefix}{key}'
+
+
+def _seconds_to_region_name(seconds: int) -> str:
+    """Convert seconds to a human-readable region name.
+    """
+    if seconds < 60:
+        return f'{seconds}s'
+    elif seconds < 3600:
+        return f'{seconds // 60}m'
+    elif seconds < 86400:
+        return f'{seconds // 3600}h'
+    else:
+        return f'{seconds // 86400}d'