cachu 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

cachu/operations.py

@@ -1,4 +1,4 @@
-"""Cache CRUD operations.
+"""Cache CRUD operations for sync and async APIs.
 """
 import logging
 from collections.abc import Callable
@@ -6,8 +6,9 @@ from typing import Any
 
 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 .decorator import async_manager, get_async_cache_info, get_cache_info
+from .decorator import manager
+from .keys import _tag_to_pattern, mangle_key
 from .types import CacheInfo, CacheMeta
 
 logger = logging.getLogger(__name__)
@@ -15,12 +16,12 @@ logger = logging.getLogger(__name__)
 _MISSING = object()
 
 
-def _get_meta(fn: Callable[..., Any]) -> CacheMeta:
+def _get_meta(fn: Callable[..., Any], decorator_name: str = '@cache') -> 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')
+        raise ValueError(f'{fn.__name__} is not decorated with {decorator_name}')
     return meta
 
 
@@ -46,7 +47,7 @@ def cache_get(fn: Callable[..., Any], default: Any = _MISSING, **kwargs: Any) ->
     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 = manager.get_backend(meta.package, meta.backend, meta.ttl)
     value = backend.get(cache_key)
 
     if value is NO_VALUE:
@@ -75,7 +76,7 @@ def cache_set(fn: Callable[..., Any], value: Any, **kwargs: Any) -> None:
     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 = manager.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}')
@@ -98,7 +99,7 @@ def cache_delete(fn: Callable[..., Any], **kwargs: Any) -> None:
     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 = manager.get_backend(meta.package, meta.backend, meta.ttl)
     backend.delete(cache_key)
 
     logger.debug(f'Deleted cache for {fn.__name__} with key {cache_key}')
@@ -129,28 +130,18 @@ def cache_clear(
     else:
         backends_to_clear = ['memory', 'file', 'redis']
 
-    if tag:
-        from .keys import _normalize_tag
-        pattern = f'*|{_normalize_tag(tag)}|*'
-    else:
-        pattern = None
-
+    pattern = _tag_to_pattern(tag)
     total_cleared = 0
 
-    from .decorator import _backends, _backends_lock
-
-    # When both backend and ttl are specified, directly get/create and clear that backend.
-    # This is essential for distributed caches (Redis) where cache_clear may be called
-    # from a different process than the one that populated the cache.
     if backend is not None and ttl is not None:
-        backend_instance = _get_backend(package, backend, ttl)
+        backend_instance = manager.get_backend(package, backend, ttl)
         cleared = backend_instance.clear(pattern)
         if cleared > 0:
             total_cleared += cleared
             logger.debug(f'Cleared {cleared} entries from {backend} backend (ttl={ttl})')
     else:
-        with _backends_lock:
-            for (pkg, btype, bttl), backend_instance in list(_backends.items()):
+        with manager._backends_lock:
+            for (pkg, btype, bttl), backend_instance in list(manager.backends.items()):
                 if pkg != package:
                     continue
                 if btype not in backends_to_clear:
@@ -163,6 +154,9 @@ def cache_clear(
                     total_cleared += cleared
                     logger.debug(f'Cleared {cleared} entries from {btype} backend (ttl={bttl})')
 
+    with manager._stats_lock:
+        manager.stats.clear()
+
     return total_cleared
 
 
@@ -178,5 +172,160 @@ def cache_info(fn: Callable[..., Any]) -> CacheInfo:
     Raises
         ValueError: If function is not decorated with @cache
     """
-    _get_meta(fn)  # Validate it's decorated
+    _get_meta(fn)
     return get_cache_info(fn)
+
+
+async def async_cache_get(
+    fn: Callable[..., Any],
+    default: Any = _MISSING,
+    **kwargs: Any,
+) -> Any:
+    """Get a cached value without calling the async function.
+
+    Args:
+        fn: A function decorated with @async_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 @async_cache
+    """
+    meta = _get_meta(fn, '@async_cache')
+    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 = await async_manager.get_backend(meta.package, meta.backend, meta.ttl)
+    value = await 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
+
+
+async def async_cache_set(fn: Callable[..., Any], value: Any, **kwargs: Any) -> None:
+    """Set a cached value directly without calling the async function.
+
+    Args:
+        fn: A function decorated with @async_cache
+        value: The value to cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @async_cache
+    """
+    meta = _get_meta(fn, '@async_cache')
+    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 = await async_manager.get_backend(meta.package, meta.backend, meta.ttl)
+    await backend.set(cache_key, value, meta.ttl)
+
+    logger.debug(f'Set cache for {fn.__name__} with key {cache_key}')
+
+
+async def async_cache_delete(fn: Callable[..., Any], **kwargs: Any) -> None:
+    """Delete a specific cached entry.
+
+    Args:
+        fn: A function decorated with @async_cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @async_cache
+    """
+    meta = _get_meta(fn, '@async_cache')
+    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 = await async_manager.get_backend(meta.package, meta.backend, meta.ttl)
+    await backend.delete(cache_key)
+
+    logger.debug(f'Deleted cache for {fn.__name__} with key {cache_key}')
+
+
+async def async_cache_clear(
+    tag: str | None = None,
+    backend: str | None = None,
+    ttl: int | None = None,
+    package: str | None = None,
+) -> int:
+    """Clear async 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()
+
+    if backend is not None:
+        backends_to_clear = [backend]
+    else:
+        backends_to_clear = ['memory', 'file', 'redis']
+
+    pattern = _tag_to_pattern(tag)
+    total_cleared = 0
+
+    if backend is not None and ttl is not None:
+        backend_instance = await async_manager.get_backend(package, backend, ttl)
+        cleared = await backend_instance.clear(pattern)
+        if cleared > 0:
+            total_cleared += cleared
+            logger.debug(f'Cleared {cleared} entries from {backend} backend (ttl={ttl})')
+    else:
+        async with async_manager._backends_lock:
+            for (pkg, btype, bttl), backend_instance in list(async_manager.backends.items()):
+                if pkg != package:
+                    continue
+                if btype not in backends_to_clear:
+                    continue
+                if ttl is not None and bttl != ttl:
+                    continue
+
+                cleared = await backend_instance.clear(pattern)
+                if cleared > 0:
+                    total_cleared += cleared
+                    logger.debug(f'Cleared {cleared} entries from {btype} backend (ttl={bttl})')
+
+    async with async_manager._stats_lock:
+        async_manager.stats.clear()
+
+    return total_cleared
+
+
+async def 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
+
+    Raises
+        ValueError: If function is not decorated with @async_cache
+    """
+    _get_meta(fn, '@async_cache')
+    return await get_async_cache_info(fn)

{cachu-0.2.3.dist-info → cachu-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachu
-Version: 0.2.3
+Version: 0.2.4
 Summary: Flexible caching library with sync and async support for memory, file (SQLite), and Redis backends
 Author: bissli
 License-Expression: 0BSD
@@ -69,19 +69,17 @@ cachu.configure(
     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                |
+| 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                              |
 
 ### Package Isolation
 

cachu-0.2.4.dist-info/RECORD

@@ -0,0 +1,21 @@
+cachu/__init__.py,sha256=JXeoRvouVGb02Vp8C97I9jEXQIuC86LoTGrXJ6lXyz4,1188
+cachu/async_decorator.py,sha256=Jx2fHESLlld7NZiD2-6kcozukJtp5efnt4cMhntDDRA,8939
+cachu/async_operations.py,sha256=eVqhZk3FVLNip_abjnCzG8AajzvJTtXbpL--dpMXBlc,5597
+cachu/config.py,sha256=ky6brQ6_yjTXHEpjx43AIOr5bCloR72sbZWS-9LVuWs,5640
+cachu/decorator.py,sha256=uEDP1FVzOj_yr57wppbLlHf-sdDQTJaOEvVtXL-JQz8,18315
+cachu/keys.py,sha256=3em9_umQYFwwF2EwmIK8yWJq8aO2CI1DMRjq6Je3xC8,3747
+cachu/operations.py,sha256=EieBJwHzTHlnXdkycKPT47ShhQ69L7ZUFVNdOyDq6SY,10371
+cachu/types.py,sha256=FghBN5GhxnrpuT4WUL9iNnAfdoH__cw9_Ag4kHbIXq4,723
+cachu/backends/__init__.py,sha256=gXzLDZ6uUEeH8pJJkOEd45-ZGRGeNnlB_bKxfREzRes,2546
+cachu/backends/async_base.py,sha256=oZ3K3PhsYkbgZxFLFk3_NbxBxtNopqS90HZBizwg_q8,1394
+cachu/backends/async_memory.py,sha256=SQvSHeWbySa52BnQLF75nhVXgsydubNu84a8hvSzQSc,3457
+cachu/backends/async_redis.py,sha256=8kefPIoIJDAZ6C6HJCvHqKFMDS10sJYh8YcJMpXpQm8,4455
+cachu/backends/async_sqlite.py,sha256=iS1YaVakzK7msKL3BVmnZc_n73-V5fUz1wCQJxEY0ak,8730
+cachu/backends/file.py,sha256=Pu01VtgHDgK6ev5hqyZXuJRCSB2VbNKHQ4w4nNKNyeI,298
+cachu/backends/memory.py,sha256=Sz1BAsttaMBqqEZfRqgYddbbwvHRNWbxm2KIzIDtZeA,6394
+cachu/backends/redis.py,sha256=Gn96-Qn2EbNti0S50f3sFGJ3A9eCWsLlGgZgBKV8AJs,7197
+cachu/backends/sqlite.py,sha256=NDhlH7Ex7kKNoS6wRvrv6qFETqUMuK8W1iL3w3yTuys,16315
+cachu-0.2.4.dist-info/METADATA,sha256=jRuDdgJ7zPk9z52T8L4uCIcQafc9dFV2TVk5R1s_6h0,11777
+cachu-0.2.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cachu-0.2.4.dist-info/top_level.txt,sha256=g80nNoMvLMzhSwQWV-JotCBqtsLAHeFMBo_g8hCK8hQ,6
+cachu-0.2.4.dist-info/RECORD,,

cachu-0.2.3.dist-info/RECORD

@@ -1,21 +0,0 @@
-cachu/__init__.py,sha256=vMcuJYvSfRUsMwlFrpjS8FOuQiqPBP9e4dRlJbsvpZ0,1286
-cachu/async_decorator.py,sha256=Jx2fHESLlld7NZiD2-6kcozukJtp5efnt4cMhntDDRA,8939
-cachu/async_operations.py,sha256=eVqhZk3FVLNip_abjnCzG8AajzvJTtXbpL--dpMXBlc,5597
-cachu/config.py,sha256=KtcDGpSTJmjRrcNLz9_Om3O814oJJ3p8gntB84Pd6Dk,5922
-cachu/decorator.py,sha256=RHwDRZxZfOkBgEK1XgRyis22bxQ0ba0X4NtHBd9FTb4,8161
-cachu/keys.py,sha256=fwwNOpnDJFCIWZoQ5UGJWhJa6xu36hsBsURI-n2NJKU,3557
-cachu/operations.py,sha256=t42_Er-O59vrwFa5jdf4yq3Jr4li2l7php4yMVJnxPs,5588
-cachu/types.py,sha256=FghBN5GhxnrpuT4WUL9iNnAfdoH__cw9_Ag4kHbIXq4,723
-cachu/backends/__init__.py,sha256=Jn2yBAMmJ8d0J_NyjOtxRt7UTyMLf1rlY8QJ049hXE8,1318
-cachu/backends/async_base.py,sha256=oZ3K3PhsYkbgZxFLFk3_NbxBxtNopqS90HZBizwg_q8,1394
-cachu/backends/async_memory.py,sha256=SQvSHeWbySa52BnQLF75nhVXgsydubNu84a8hvSzQSc,3457
-cachu/backends/async_redis.py,sha256=8kefPIoIJDAZ6C6HJCvHqKFMDS10sJYh8YcJMpXpQm8,4455
-cachu/backends/async_sqlite.py,sha256=iS1YaVakzK7msKL3BVmnZc_n73-V5fUz1wCQJxEY0ak,8730
-cachu/backends/file.py,sha256=Pu01VtgHDgK6ev5hqyZXuJRCSB2VbNKHQ4w4nNKNyeI,298
-cachu/backends/memory.py,sha256=kIgrVU8k_3Aquyj2PDf8IPbTjCITM_0V5GU47m3fJmo,3138
-cachu/backends/redis.py,sha256=yE5rEBgOij9QOeC1VhWdIbGCgi442q-aWfmbbG4aNSE,3858
-cachu/backends/sqlite.py,sha256=whduN5G_bN6ZJNuCBwbraDcadv_sg0j-OEiFnP8EEsk,7803
-cachu-0.2.3.dist-info/METADATA,sha256=UXittsVjHwFjAGq6Fl8LAS_2zTKs14BYc9KvOEJHX9I,11992
-cachu-0.2.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-cachu-0.2.3.dist-info/top_level.txt,sha256=g80nNoMvLMzhSwQWV-JotCBqtsLAHeFMBo_g8hCK8hQ,6
-cachu-0.2.3.dist-info/RECORD,,