cachu 0.1.2__tar.gz → 0.2.0__tar.gz

{cachu-0.1.2/src/cachu.egg-info → cachu-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cachu
-Version: 0.1.2
-Summary: Flexible caching library built on dogpile.cache
+Version: 0.2.0
+Summary: Flexible caching library with sync and async support for memory, file (SQLite), and Redis backends
 Author: bissli
 License-Expression: 0BSD
 Project-URL: Repository, https://github.com/bissli/cachu.git
@@ -9,13 +9,17 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: dogpile.cache
 Requires-Dist: func-timeout
+Provides-Extra: async
+Requires-Dist: aiosqlite; extra == "async"
 Provides-Extra: redis
-Requires-Dist: redis; extra == "redis"
+Requires-Dist: redis>=4.2.0; extra == "redis"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: pytest-mock; extra == "test"
-Requires-Dist: redis; extra == "test"
+Requires-Dist: redis>=4.2.0; extra == "test"
 Requires-Dist: testcontainers[redis]; extra == "test"
+Requires-Dist: aiosqlite; extra == "test"
 
 # cachu
 
@@ -71,17 +75,17 @@ cachu.configure(
 
 ### 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 |
+| 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:
+Each package automatically gets isolated configuration, preventing conflicts when multiple libraries use cachu:
 
 ```python
 # In library_a/config.py
@@ -92,7 +96,18 @@ cachu.configure(key_prefix='lib_a:', redis_url='redis://redis-a:6379/0')
 import cachu
 cachu.configure(key_prefix='lib_b:', redis_url='redis://redis-b:6379/0')
 
-# Each library uses its own configuration automatically
+# Each library's @cache calls use its own configuration automatically
+```
+
+To override the automatic detection, specify the `package` parameter:
+
+```python
+from cachu import cache
+
+# This function will use library_a's configuration
+@cache(ttl=300, package='library_a')
+def get_shared_data(id: int) -> dict:
+    return fetch(id)
 ```
 
 Retrieve configuration:
@@ -289,12 +304,12 @@ 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 |
+| `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
 
@@ -352,6 +367,38 @@ if cachu.is_disabled():
     print("Caching is disabled")
 ```
 
+## Async Support
+
+The library provides full async/await support with matching APIs:
+
+```python
+from cachu import async_cache, async_cache_get, async_cache_set, async_cache_delete
+from cachu import async_cache_clear, async_cache_info
+
+@async_cache(ttl=300, backend='memory')
+async def get_user(user_id: int) -> dict:
+    return await fetch_from_database(user_id)
+
+# Usage
+user = await get_user(123)  # Cache miss
+user = await get_user(123)  # Cache hit
+
+# Per-call control works the same way
+user = await get_user(123, _skip_cache=True)
+user = await get_user(123, _overwrite_cache=True)
+
+# CRUD operations
+cached = await async_cache_get(get_user, user_id=123)
+await async_cache_set(get_user, {'id': 123, 'name': 'Test'}, user_id=123)
+await async_cache_delete(get_user, user_id=123)
+await async_cache_clear(backend='memory', ttl=300)
+
+# Statistics
+info = await async_cache_info(get_user)
+```
+
+All decorator options (`ttl`, `backend`, `tag`, `exclude`, `cache_if`, `validate`, `package`) work identically to the sync version.
+
 ## Advanced
 
 ### Direct Backend Access
@@ -386,25 +433,40 @@ from cachu import (
     enable,
     is_disabled,
 
-    # Decorator
+    # Sync Decorator
     cache,
 
-    # CRUD Operations
+    # Sync CRUD Operations
     cache_get,
     cache_set,
     cache_delete,
     cache_clear,
     cache_info,
 
+    # Async Decorator
+    async_cache,
+
+    # Async CRUD Operations
+    async_cache_get,
+    async_cache_set,
+    async_cache_delete,
+    async_cache_clear,
+    async_cache_info,
+
     # Advanced
     get_backend,
+    get_async_backend,
     get_redis_client,
+    Backend,
+    AsyncBackend,
+    clear_async_backends,
 )
 ```
 
 ## Features
 
-- **Multiple backends**: Memory, file (DBM), and Redis
+- **Multiple backends**: Memory, file (SQLite), and Redis
+- **Async support**: Full async/await API with `@async_cache` decorator
 - **Flexible TTL**: Configure different TTLs for different use cases
 - **Tags**: Organize and selectively clear cache entries
 - **Package isolation**: Each package gets isolated configuration

cachu-0.1.2/PKG-INFO → cachu-0.2.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: cachu
-Version: 0.1.2
-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: redis; extra == "test"
-Requires-Dist: testcontainers[redis]; extra == "test"
-
 # cachu
 
 Flexible caching library with support for memory, file, and Redis backends.
@@ -71,17 +52,17 @@ cachu.configure(
 
 ### 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 |
+| 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:
+Each package automatically gets isolated configuration, preventing conflicts when multiple libraries use cachu:
 
 ```python
 # In library_a/config.py
@@ -92,7 +73,18 @@ cachu.configure(key_prefix='lib_a:', redis_url='redis://redis-a:6379/0')
 import cachu
 cachu.configure(key_prefix='lib_b:', redis_url='redis://redis-b:6379/0')
 
-# Each library uses its own configuration automatically
+# Each library's @cache calls use its own configuration automatically
+```
+
+To override the automatic detection, specify the `package` parameter:
+
+```python
+from cachu import cache
+
+# This function will use library_a's configuration
+@cache(ttl=300, package='library_a')
+def get_shared_data(id: int) -> dict:
+    return fetch(id)
 ```
 
 Retrieve configuration:
@@ -289,12 +281,12 @@ 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 |
+| `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
 
@@ -352,6 +344,38 @@ if cachu.is_disabled():
     print("Caching is disabled")
 ```
 
+## Async Support
+
+The library provides full async/await support with matching APIs:
+
+```python
+from cachu import async_cache, async_cache_get, async_cache_set, async_cache_delete
+from cachu import async_cache_clear, async_cache_info
+
+@async_cache(ttl=300, backend='memory')
+async def get_user(user_id: int) -> dict:
+    return await fetch_from_database(user_id)
+
+# Usage
+user = await get_user(123)  # Cache miss
+user = await get_user(123)  # Cache hit
+
+# Per-call control works the same way
+user = await get_user(123, _skip_cache=True)
+user = await get_user(123, _overwrite_cache=True)
+
+# CRUD operations
+cached = await async_cache_get(get_user, user_id=123)
+await async_cache_set(get_user, {'id': 123, 'name': 'Test'}, user_id=123)
+await async_cache_delete(get_user, user_id=123)
+await async_cache_clear(backend='memory', ttl=300)
+
+# Statistics
+info = await async_cache_info(get_user)
+```
+
+All decorator options (`ttl`, `backend`, `tag`, `exclude`, `cache_if`, `validate`, `package`) work identically to the sync version.
+
 ## Advanced
 
 ### Direct Backend Access
@@ -386,25 +410,40 @@ from cachu import (
     enable,
     is_disabled,
 
-    # Decorator
+    # Sync Decorator
     cache,
 
-    # CRUD Operations
+    # Sync CRUD Operations
     cache_get,
     cache_set,
     cache_delete,
     cache_clear,
     cache_info,
 
+    # Async Decorator
+    async_cache,
+
+    # Async CRUD Operations
+    async_cache_get,
+    async_cache_set,
+    async_cache_delete,
+    async_cache_clear,
+    async_cache_info,
+
     # Advanced
     get_backend,
+    get_async_backend,
     get_redis_client,
+    Backend,
+    AsyncBackend,
+    clear_async_backends,
 )
 ```
 
 ## Features
 
-- **Multiple backends**: Memory, file (DBM), and Redis
+- **Multiple backends**: Memory, file (SQLite), and Redis
+- **Async support**: Full async/await API with `@async_cache` decorator
 - **Flexible TTL**: Configure different TTLs for different use cases
 - **Tags**: Organize and selectively clear cache entries
 - **Package isolation**: Each package gets isolated configuration

{cachu-0.1.2 → cachu-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "cachu"
-version = "0.1.2"
-description = "Flexible caching library built on dogpile.cache"
+version = "0.2.0"
+description = "Flexible caching library with sync and async support for memory, file (SQLite), and Redis backends"
 readme = "README.md"
 license = "0BSD"
 authors = [{ name = "bissli" }]
@@ -12,12 +12,15 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-redis = ["redis"]
+async = ["aiosqlite"]
+redis = ["redis>=4.2.0"]
 test = [
     "pytest",
+    "pytest-asyncio",
     "pytest-mock",
-    "redis",
+    "redis>=4.2.0",
     "testcontainers[redis]",
+    "aiosqlite",
 ]
 
 [project.urls]
@@ -31,6 +34,7 @@ testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
+asyncio_mode = "auto"
 markers = [
   "redis: marks tests requiring Redis (deselect with '-m \"not redis\"')",
   "slow: marks tests as slow (deselect with '-m \"not slow\"')",

{cachu-0.1.2 → cachu-0.2.0}/setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.1.2
+current_version = 0.2.0
 commit = True
 tag = True
 

{cachu-0.1.2 → cachu-0.2.0}/src/cachu/__init__.py

@@ -1,7 +1,13 @@
 """Flexible caching library with support for memory, file, and Redis backends.
 """
-__version__ = '0.1.2'
+__version__ = '0.2.0'
 
+from .async_decorator import async_cache, clear_async_backends
+from .async_decorator import get_async_backend, get_async_cache_info
+from .async_operations import async_cache_clear, async_cache_delete
+from .async_operations import async_cache_get, async_cache_info
+from .async_operations import async_cache_set
+from .backends import AsyncBackend, Backend
 from .backends.redis import get_redis_client
 from .config import configure, disable, enable, get_all_configs, get_config
 from .config import is_disabled
@@ -24,4 +30,15 @@ __all__ = [
     'cache_info',
     'get_backend',
     'get_redis_client',
+    'Backend',
+    'AsyncBackend',
+    'async_cache',
+    'async_cache_get',
+    'async_cache_set',
+    'async_cache_delete',
+    'async_cache_clear',
+    'async_cache_info',
+    'get_async_backend',
+    'get_async_cache_info',
+    'clear_async_backends',
 ]

cachu-0.2.0/src/cachu/async_decorator.py

@@ -0,0 +1,261 @@
+"""Async cache decorator implementation.
+"""
+import asyncio
+import logging
+import os
+import time
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any
+
+from .backends import NO_VALUE
+from .backends.async_base import AsyncBackend
+from .backends.async_memory import AsyncMemoryBackend
+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__)
+
+_async_backends: dict[tuple[str | None, str, int], AsyncBackend] = {}
+_async_backends_lock = asyncio.Lock()
+
+_async_stats: dict[int, tuple[int, int]] = {}
+_async_stats_lock = asyncio.Lock()
+
+
+async def _get_async_backend(package: str | None, backend_type: str, ttl: int) -> AsyncBackend:
+    """Get or create an async backend instance.
+    """
+    key = (package, backend_type, ttl)
+
+    async with _async_backends_lock:
+        if key in _async_backends:
+            return _async_backends[key]
+
+        cfg = get_config(package)
+
+        if backend_type == 'memory':
+            backend: AsyncBackend = AsyncMemoryBackend()
+        elif backend_type == 'file':
+            from .backends.async_sqlite import AsyncSqliteBackend
+
+            if ttl < 60:
+                filename = f'cache{ttl}sec.db'
+            elif ttl < 3600:
+                filename = f'cache{ttl // 60}min.db'
+            else:
+                filename = f'cache{ttl // 3600}hour.db'
+
+            if package:
+                filename = f'{package}_{filename}'
+
+            filepath = os.path.join(cfg.file_dir, filename)
+            backend = AsyncSqliteBackend(filepath)
+        elif backend_type == 'redis':
+            from .backends.async_redis import AsyncRedisBackend
+            backend = AsyncRedisBackend(cfg.redis_url, cfg.redis_distributed)
+        else:
+            raise ValueError(f'Unknown backend type: {backend_type}')
+
+        _async_backends[key] = backend
+        logger.debug(f"Created async {backend_type} backend for package '{package}', {ttl}s TTL")
+        return backend
+
+
+async def get_async_backend(
+    backend_type: str | None = None,
+    package: str | None = None,
+    ttl: int = 300,
+) -> AsyncBackend:
+    """Get an async 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 await _get_async_backend(package, backend_type, ttl)
+
+
+def async_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[..., Awaitable[Any]]], Callable[..., Awaitable[Any]]]:
+    """Async 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:
+        @async_cache(ttl=300, tag='users')
+        async def get_user(user_id: int) -> dict:
+            return await fetch_user(user_id)
+
+        # Normal call
+        user = await get_user(123)
+
+        # Skip cache
+        user = await get_user(123, _skip_cache=True)
+
+        # Force refresh
+        user = await 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[..., Awaitable[Any]]) -> Callable[..., Awaitable[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)
+        async 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 await fn(*args, **kwargs)
+
+            backend_instance = await _get_async_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 = await 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:
+                            await _record_async_hit(wrapper)
+                            return value
+                    else:
+                        await _record_async_hit(wrapper)
+                        return value
+
+            await _record_async_miss(wrapper)
+            result = await fn(*args, **kwargs)
+
+            should_cache = cache_if is None or cache_if(result)
+
+            if should_cache:
+                await 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
+
+
+async def _record_async_hit(fn: Callable[..., Any]) -> None:
+    """Record a cache hit for the async function.
+    """
+    fn_id = id(fn)
+    async with _async_stats_lock:
+        hits, misses = _async_stats.get(fn_id, (0, 0))
+        _async_stats[fn_id] = (hits + 1, misses)
+
+
+async def _record_async_miss(fn: Callable[..., Any]) -> None:
+    """Record a cache miss for the async function.
+    """
+    fn_id = id(fn)
+    async with _async_stats_lock:
+        hits, misses = _async_stats.get(fn_id, (0, 0))
+        _async_stats[fn_id] = (hits, misses + 1)
+
+
+async def get_async_cache_info(fn: Callable[..., Any]) -> CacheInfo:
+    """Get cache statistics for an async decorated function.
+
+    Args:
+        fn: A function decorated with @async_cache
+
+    Returns
+        CacheInfo with hits, misses, and currsize
+    """
+    fn_id = id(fn)
+
+    async with _async_stats_lock:
+        hits, misses = _async_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 = await _get_async_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 = await backend_instance.count(pattern)
+
+    return CacheInfo(hits=hits, misses=misses, currsize=currsize)
+
+
+async def clear_async_backends(package: str | None = None) -> None:
+    """Clear all async backend instances for a package. Primarily for testing.
+    """
+    async with _async_backends_lock:
+        if package is None:
+            for backend in _async_backends.values():
+                await backend.close()
+            _async_backends.clear()
+        else:
+            keys_to_delete = [k for k in _async_backends if k[0] == package]
+            for key in keys_to_delete:
+                await _async_backends[key].close()
+                del _async_backends[key]