cachu 0.1.1__py3-none-any.whl

cachu/operations.py

@@ -0,0 +1,174 @@
+"""Cache CRUD operations.
+"""
+import logging
+from typing import Any
+from collections.abc import Callable
+
+from .backends import NO_VALUE
+from .config import _get_caller_package, get_config
+from .decorator import _get_backend, get_cache_info
+from .keys import mangle_key
+from .types import CacheInfo, CacheMeta
+
+logger = logging.getLogger(__name__)
+
+_MISSING = object()
+
+
+def _get_meta(fn: Callable[..., Any]) -> CacheMeta:
+    """Get CacheMeta from a decorated function.
+    """
+    meta = getattr(fn, '_cache_meta', None)
+    if meta is None:
+        raise ValueError(f'{fn.__name__} is not decorated with @cache')
+    return meta
+
+
+def cache_get(fn: Callable[..., Any], default: Any = _MISSING, **kwargs: Any) -> Any:
+    """Get a cached value without calling the function.
+
+    Args:
+        fn: A function decorated with @cache
+        default: Value to return if not found (raises KeyError if not provided)
+        **kwargs: Function arguments to build the cache key
+
+    Returns
+        The cached value or default
+
+    Raises
+        KeyError: If not found and no default provided
+        ValueError: If function is not decorated with @cache
+    """
+    meta = _get_meta(fn)
+    cfg = get_config(meta.package)
+
+    key_generator = fn._cache_key_generator
+    base_key = key_generator(**kwargs)
+    cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
+
+    backend = _get_backend(meta.package, meta.backend, meta.ttl)
+    value = backend.get(cache_key)
+
+    if value is NO_VALUE:
+        if default is _MISSING:
+            raise KeyError(f'No cached value for {fn.__name__} with {kwargs}')
+        return default
+
+    return value
+
+
+def cache_set(fn: Callable[..., Any], value: Any, **kwargs: Any) -> None:
+    """Set a cached value directly without calling the function.
+
+    Args:
+        fn: A function decorated with @cache
+        value: The value to cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @cache
+    """
+    meta = _get_meta(fn)
+    cfg = get_config(meta.package)
+
+    key_generator = fn._cache_key_generator
+    base_key = key_generator(**kwargs)
+    cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
+
+    backend = _get_backend(meta.package, meta.backend, meta.ttl)
+    backend.set(cache_key, value, meta.ttl)
+
+    logger.debug(f'Set cache for {fn.__name__} with key {cache_key}')
+
+
+def cache_delete(fn: Callable[..., Any], **kwargs: Any) -> None:
+    """Delete a specific cached entry.
+
+    Args:
+        fn: A function decorated with @cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @cache
+    """
+    meta = _get_meta(fn)
+    cfg = get_config(meta.package)
+
+    key_generator = fn._cache_key_generator
+    base_key = key_generator(**kwargs)
+    cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
+
+    backend = _get_backend(meta.package, meta.backend, meta.ttl)
+    backend.delete(cache_key)
+
+    logger.debug(f'Deleted cache for {fn.__name__} with key {cache_key}')
+
+
+def cache_clear(
+    tag: str | None = None,
+    backend: str | None = None,
+    ttl: int | None = None,
+    package: str | None = None,
+) -> int:
+    """Clear cache entries matching criteria.
+
+    Args:
+        tag: Clear only entries with this tag
+        backend: Backend type to clear ('memory', 'file', 'redis'). Clears all if None.
+        ttl: Specific TTL region to clear. Clears all TTLs if None.
+        package: Package to clear for. Auto-detected if None.
+
+    Returns
+        Number of entries cleared (may be approximate)
+    """
+    if package is None:
+        package = _get_caller_package()
+
+    cfg = get_config(package)
+
+    if backend is not None:
+        backends_to_clear = [backend]
+    else:
+        backends_to_clear = ['memory', 'file', 'redis']
+
+    if tag:
+        from .keys import _normalize_tag
+        pattern = f'*|{_normalize_tag(tag)}|*'
+    else:
+        pattern = None
+
+    total_cleared = 0
+
+    from .decorator import _backends, _backends_lock
+
+    with _backends_lock:
+        for (pkg, btype, bttl), backend_instance in list(_backends.items()):
+            if pkg != package:
+                continue
+            if btype not in backends_to_clear:
+                continue
+            if ttl is not None and bttl != ttl:
+                continue
+
+            cleared = backend_instance.clear(pattern)
+            if cleared > 0:
+                total_cleared += cleared
+                logger.debug(f'Cleared {cleared} entries from {btype} backend (ttl={bttl})')
+
+    return total_cleared
+
+
+def 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
+
+    Raises
+        ValueError: If function is not decorated with @cache
+    """
+    _get_meta(fn)  # Validate it's decorated
+    return get_cache_info(fn)

cachu/types.py

@@ -0,0 +1,37 @@
+"""Type definitions for the cache library.
+"""
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class CacheEntry:
+    """Cache entry metadata passed to validate callbacks.
+    """
+    value: Any
+    created_at: float
+    age: float
+
+
+@dataclass
+class CacheInfo:
+    """Cache statistics for a decorated function.
+    """
+    hits: int
+    misses: int
+    currsize: int
+
+
+@dataclass
+class CacheMeta:
+    """Metadata attached to cached functions.
+    """
+    ttl: int
+    backend: str
+    tag: str
+    exclude: set[str]
+    cache_if: Callable[[Any], bool] | None
+    validate: Callable[[CacheEntry], bool] | None
+    package: str
+    key_generator: Callable[..., str]

cachu-0.1.1.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: cachu
+Version: 0.1.1
+Summary: Flexible caching library built on dogpile.cache
+Author: bissli
+License-Expression: 0BSD
+Project-URL: Repository, https://github.com/bissli/cachu.git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: dogpile.cache
+Requires-Dist: func-timeout
+Provides-Extra: redis
+Requires-Dist: redis; extra == "redis"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: testcontainers[redis]; extra == "test"
+
+# cachu
+
+Flexible caching library with support for memory, file, and Redis backends.
+
+## Installation
+
+**Basic installation:**
+
+```bash
+pip install git+https://github.com/bissli/cachu.git
+```
+
+**With Redis support:**
+
+```bash
+pip install git+https://github.com/bissli/cachu.git#egg=cachu[redis]
+```
+
+## Quick Start
+
+```python
+import cachu
+
+# Configure once at startup
+cachu.configure(backend='memory', key_prefix='v1:')
+
+# Use the @cache decorator
+@cachu.cache(ttl=300)
+def get_user(user_id: int) -> dict:
+    return fetch_from_database(user_id)
+
+# Cached automatically
+user = get_user(123)  # Cache miss - fetches from DB
+user = get_user(123)  # Cache hit - returns cached value
+```
+
+## Configuration
+
+Configure cache settings at application startup:
+
+```python
+import cachu
+
+cachu.configure(
+    backend='memory',           # Default backend: 'memory', 'file', or 'redis'
+    key_prefix='v1:',           # Prefix for all cache keys
+    file_dir='/var/cache/app',  # Directory for file cache
+    redis_url='redis://localhost:6379/0',  # Redis connection URL
+    redis_distributed=False,    # Use distributed locks for Redis
+)
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `backend` | `'memory'` | Default backend type |
+| `key_prefix` | `''` | Prefix for all cache keys (useful for versioning) |
+| `file_dir` | `'/tmp'` | Directory for file-based caches |
+| `redis_url` | `'redis://localhost:6379/0'` | Redis connection URL |
+| `redis_distributed` | `False` | Enable distributed locks for Redis |
+
+### Package Isolation
+
+Each package automatically gets isolated configuration. This prevents conflicts when multiple libraries use the cachu package:
+
+```python
+# In library_a/config.py
+import cachu
+cachu.configure(key_prefix='lib_a:', redis_url='redis://redis-a:6379/0')
+
+# In library_b/config.py
+import cachu
+cachu.configure(key_prefix='lib_b:', redis_url='redis://redis-b:6379/0')
+
+# Each library uses its own configuration automatically
+```
+
+Retrieve configuration:
+
+```python
+cfg = cachu.get_config()                    # Current package's config
+cfg = cachu.get_config(package='mylib')     # Specific package's config
+all_configs = cachu.get_all_configs()       # All configurations
+```
+
+## Usage
+
+### Basic Caching
+
+```python
+from cachu import cachu
+
+@cache(ttl=300, backend='memory')
+def expensive_operation(param: str) -> dict:
+    return compute_result(param)
+```
+
+### Backend Types
+
+```python
+# Memory cache (default)
+@cache(ttl=300, backend='memory')
+def fast_lookup(key: str) -> str:
+    return fetch(key)
+
+# File cache (persists across restarts)
+@cache(ttl=3600, backend='file')
+def load_config(name: str) -> dict:
+    return parse_config_file(name)
+
+# Redis cache (shared across processes)
+@cache(ttl=86400, backend='redis')
+def fetch_external_data(api_key: str) -> dict:
+    return call_external_api(api_key)
+```
+
+### Tags for Grouping
+
+Tags organize cache entries into logical groups for selective clearing:
+
+```python
+@cache(ttl=300, tag='users')
+def get_user(user_id: int) -> dict:
+    return fetch_user(user_id)
+
+@cache(ttl=300, tag='products')
+def get_product(product_id: int) -> dict:
+    return fetch_product(product_id)
+
+# Clear only user caches
+cachu.cache_clear(tag='users', backend='memory', ttl=300)
+```
+
+### Conditional Caching
+
+Cache results only when a condition is met:
+
+```python
+# Don't cache None results
+@cache(ttl=300, cache_if=lambda result: result is not None)
+def find_user(email: str) -> dict | None:
+    return db.find_by_email(email)
+
+# Don't cache empty lists
+@cache(ttl=300, cache_if=lambda result: len(result) > 0)
+def search(query: str) -> list:
+    return db.search(query)
+```
+
+### Validation Callbacks
+
+Validate cached entries before returning:
+
+```python
+@cache(ttl=3600, validate=lambda entry: entry.age < 1800)
+def get_price(symbol: str) -> float:
+    # TTL is 1 hour, but recompute after 30 minutes
+    return fetch_live_price(symbol)
+
+# Validate based on value
+def check_version(entry):
+    return entry.value.get('version') == CURRENT_VERSION
+
+@cache(ttl=86400, validate=check_version)
+def get_config() -> dict:
+    return load_config()
+```
+
+The `entry` parameter is a `CacheEntry` with:
+- `value`: The cached value
+- `created_at`: Unix timestamp when cached
+- `age`: Seconds since creation
+
+### Per-Call Control
+
+Control caching behavior for individual calls:
+
+```python
+@cache(ttl=300)
+def get_data(id: int) -> dict:
+    return fetch(id)
+
+# Normal call - uses cache
+result = get_data(123)
+
+# Skip cache for this call only (don't read or write cache)
+result = get_data(123, _skip_cache=True)
+
+# Force refresh - execute and overwrite cached value
+result = get_data(123, _overwrite_cache=True)
+```
+
+### Cache Statistics
+
+Track hits and misses:
+
+```python
+@cache(ttl=300)
+def get_user(user_id: int) -> dict:
+    return fetch_user(user_id)
+
+# After some usage
+info = cachu.cache_info(get_user)
+print(f"Hits: {info.hits}, Misses: {info.misses}, Size: {info.currsize}")
+```
+
+### Excluding Parameters
+
+Exclude parameters from the cache key:
+
+```python
+@cache(ttl=300, exclude={'logger', 'context'})
+def process_data(logger, context, user_id: int, data: str) -> dict:
+    logger.info(f"Processing for user {user_id}")
+    return compute(data)
+
+# Different logger/context values use the same cache entry
+process_data(logger1, ctx1, 123, 'test')  # Cache miss
+process_data(logger2, ctx2, 123, 'test')  # Cache hit
+```
+
+**Automatic filtering**: The library automatically excludes:
+- `self` and `cls` parameters
+- Parameters starting with underscore (`_`)
+- Database connection objects
+
+## CRUD Operations
+
+### Direct Cache Manipulation
+
+```python
+from cachu import cache_get, cache_set, cache_delete, cache_clear
+
+@cache(ttl=300, tag='users')
+def get_user(user_id: int) -> dict:
+    return fetch_user(user_id)
+
+# Get cached value without calling function
+user = cache_get(get_user, user_id=123, default=None)
+
+# Set cache value directly
+cache_set(get_user, {'id': 123, 'name': 'Updated'}, user_id=123)
+
+# Delete specific cache entry
+cache_delete(get_user, user_id=123)
+```
+
+### Clearing Caches
+
+```python
+from cachu import cachu_clear
+
+# Clear specific region
+cache_clear(backend='memory', ttl=300)
+
+# Clear by tag
+cache_clear(tag='users', backend='memory', ttl=300)
+
+# Clear all TTLs for a backend
+cache_clear(backend='memory')
+
+# Clear everything
+cache_clear()
+```
+
+**Clearing behavior:**
+
+| `ttl` | `tag` | `backend` | Behavior |
+|-------|-------|-----------|----------|
+| `300` | `None` | `'memory'` | All keys in 300s memory region |
+| `300` | `'users'` | `'memory'` | Only "users" tag in 300s memory region |
+| `None` | `None` | `'memory'` | All memory regions |
+| `None` | `'users'` | `None` | "users" tag across all backends |
+
+### Cross-Module Clearing
+
+When clearing from a different module, use the `package` parameter:
+
+```python
+# In myapp/service.py
+@cache(ttl=300)
+def get_data(id: int) -> dict:
+    return fetch(id)
+
+# In tests/conftest.py
+cachu.cache_clear(backend='memory', ttl=300, package='myapp')
+```
+
+## Instance and Class Methods
+
+```python
+class UserRepository:
+    def __init__(self, db):
+        self.db = db
+
+    @cache(ttl=300)
+    def get_user(self, user_id: int) -> dict:
+        return self.db.fetch(user_id)
+
+    @classmethod
+    @cache(ttl=300)
+    def get_default_user(cls) -> dict:
+        return cls.DEFAULT_USER
+
+    @staticmethod
+    @cache(ttl=300)
+    def get_guest() -> dict:
+        return {'id': 0, 'name': 'Guest'}
+```
+
+## Testing
+
+Disable caching globally for tests:
+
+```python
+import cachu
+import pytest
+
+@pytest.fixture(autouse=True)
+def disable_caching():
+    cachu.disable()
+    yield
+    cachu.enable()
+
+# Check state
+if cachu.is_disabled():
+    print("Caching is disabled")
+```
+
+## Advanced
+
+### Direct Backend Access
+
+```python
+from cachu import get_backend
+
+backend = get_backend('memory', ttl=300)
+backend.set('my_key', {'data': 'value'}, ttl=300)
+value = backend.get('my_key')
+backend.delete('my_key')
+```
+
+### Redis Client Access
+
+```python
+from cachu import get_redis_client
+
+client = get_redis_client()
+client.set('direct_key', 'value')
+```
+
+## Public API
+
+```python
+from cachu import (
+    # Configuration
+    configure,
+    get_config,
+    get_all_configs,
+    disable,
+    enable,
+    is_disabled,
+
+    # Decorator
+    cache,
+
+    # CRUD Operations
+    cache_get,
+    cache_set,
+    cache_delete,
+    cache_clear,
+    cache_info,
+
+    # Advanced
+    get_backend,
+    get_redis_client,
+)
+```
+
+## Features
+
+- **Multiple backends**: Memory, file (DBM), and Redis
+- **Flexible TTL**: Configure different TTLs for different use cases
+- **Tags**: Organize and selectively clear cache entries
+- **Package isolation**: Each package gets isolated configuration
+- **Conditional caching**: Cache based on result value
+- **Validation callbacks**: Validate entries before returning
+- **Per-call control**: Skip or overwrite cache per call
+- **Statistics**: Track hits, misses, and cache size
+- **Intelligent filtering**: Auto-excludes `self`, `cls`, connections, and `_` params
+- **Global disable**: Bypass all caching for testing

cachu-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+cachu/__init__.py,sha256=snSKE_XCc1SikF_FiyolTjTVc5E52QtXjvaXEQJqHs0,676
+cachu/cache.py,sha256=UOh1hsvo5wqpf-quU0glGZi5bgjF8gkaSmYIkAwWfUA,23362
+cachu/config.py,sha256=KtcDGpSTJmjRrcNLz9_Om3O814oJJ3p8gntB84Pd6Dk,5922
+cachu/decorator.py,sha256=FqD-On66WYYIAOWIe-umlILFc8XcuE8IQHTV6MnFA9o,8254
+cachu/keys.py,sha256=fwwNOpnDJFCIWZoQ5UGJWhJa6xu36hsBsURI-n2NJKU,3557
+cachu/operations.py,sha256=_hHFo9mBgsGT_45-08rprddxNhnGAezCFbQAR_CgI80,5001
+cachu/types.py,sha256=FghBN5GhxnrpuT4WUL9iNnAfdoH__cw9_Ag4kHbIXq4,723
+cachu/backends/__init__.py,sha256=dM6NfSRXMCOeTg9A9-scgiT_6r_BfzbmT1GVNqL6egU,1228
+cachu/backends/file.py,sha256=2ssQmqvpLRDLX21joXRZKxfHekjAjb5gd_gHt52SgVA,5313
+cachu/backends/memory.py,sha256=kIgrVU8k_3Aquyj2PDf8IPbTjCITM_0V5GU47m3fJmo,3138
+cachu/backends/redis.py,sha256=yE5rEBgOij9QOeC1VhWdIbGCgi442q-aWfmbbG4aNSE,3858
+cachu-0.1.1.dist-info/METADATA,sha256=G8ue2kOMja2ER0KKUjKDDjVetNYS7OKJcQp1r-oWYY4,9629
+cachu-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cachu-0.1.1.dist-info/top_level.txt,sha256=g80nNoMvLMzhSwQWV-JotCBqtsLAHeFMBo_g8hCK8hQ,6
+cachu-0.1.1.dist-info/RECORD,,

cachu-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cachu-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cachu