nb-cache 0.1.0__py3-none-any.whl

nb_cache/__init__.py

@@ -0,0 +1,97 @@
+# -*- coding: utf-8 -*-
+"""nb_cache — 更强的缓存装饰器
+
+支持同步和异步函数，支持加锁防止缓存击穿，
+支持内存和Redis作为缓存器，支持Redis+内存双缓存提高性能。
+
+Usage::
+
+    from nb_cache import Cache
+
+    cache = Cache()
+    cache.setup("mem://")
+
+    @cache.cache(ttl=60)
+    def get_data(key):
+        return expensive_query(key)
+
+    @cache.cache(ttl="1h", lock=True)
+    async def get_data_async(key):
+        return await expensive_query_async(key)
+"""
+
+__version__ = "0.1.0"
+
+from nb_cache.wrapper import Cache, register_backend
+from nb_cache.condition import NOT_NONE, with_exceptions, only_exceptions
+from nb_cache.exceptions import (
+    CacheError,
+    BackendNotInitializedError,
+    CacheBackendInteractionError,
+    LockError,
+    LockedError,
+    CircuitBreakerOpen,
+    RateLimitError,
+    SerializationError,
+    TagError,
+)
+from nb_cache.transaction import TransactionMode
+from nb_cache.key import get_cache_key_template
+from nb_cache.helpers import noself, add_prefix, memory_limit, invalidate_further
+from nb_cache.serialize import (
+    Serializer,
+    PickleSerializer,
+    JsonSerializer,
+    GzipCompressor,
+    ZlibCompressor,
+    HashSigner,
+)
+from nb_cache.ttl import ttl_to_seconds
+from nb_cache.backends.base import BaseBackend
+from nb_cache.backends.memory import MemoryBackend
+
+mem = Cache()
+mem.setup("mem://")
+
+__all__ = [
+    '__version__',
+    # Main class
+    'Cache',
+    'mem',
+    # Conditions
+    'NOT_NONE',
+    'with_exceptions',
+    'only_exceptions',
+    # Exceptions
+    'CacheError',
+    'BackendNotInitializedError',
+    'CacheBackendInteractionError',
+    'LockError',
+    'LockedError',
+    'CircuitBreakerOpen',
+    'RateLimitError',
+    'SerializationError',
+    'TagError',
+    # Transaction
+    'TransactionMode',
+    # Key
+    'get_cache_key_template',
+    # Helpers
+    'noself',
+    'add_prefix',
+    'memory_limit',
+    'invalidate_further',
+    # Serialization
+    'Serializer',
+    'PickleSerializer',
+    'JsonSerializer',
+    'GzipCompressor',
+    'ZlibCompressor',
+    'HashSigner',
+    # TTL
+    'ttl_to_seconds',
+    # Backends
+    'BaseBackend',
+    'MemoryBackend',
+    'register_backend',
+]

nb_cache/_compat.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""Python version compatibility utilities for Python 3.6+."""
+import sys
+import asyncio
+import inspect
+
+PY36 = sys.version_info[:2] == (3, 6)
+PY37_PLUS = sys.version_info >= (3, 7)
+PY38_PLUS = sys.version_info >= (3, 8)
+PY310_PLUS = sys.version_info >= (3, 10)
+
+
+def get_event_loop():
+    if PY310_PLUS:
+        try:
+            return asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.new_event_loop()
+    else:
+        return asyncio.get_event_loop()
+
+
+def is_coroutine_function(func):
+    if hasattr(func, '__wrapped__'):
+        return asyncio.iscoroutinefunction(func.__wrapped__)
+    return asyncio.iscoroutinefunction(func)
+
+
+def create_task(coro):
+    loop = get_event_loop()
+    if hasattr(loop, 'create_task'):
+        return loop.create_task(coro)
+    return asyncio.ensure_future(coro, loop=loop)
+
+
+def run_sync(coro):
+    """Run a coroutine synchronously. Works across Python versions."""
+    if PY37_PLUS:
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                import concurrent.futures
+                with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                    future = pool.submit(asyncio.run, coro)
+                    return future.result()
+            else:
+                return loop.run_until_complete(coro)
+        except RuntimeError:
+            return asyncio.run(coro)
+    else:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                new_loop = asyncio.new_event_loop()
+                future = pool.submit(new_loop.run_until_complete, coro)
+                return future.result()
+        return loop.run_until_complete(coro)

nb_cache/backends/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+from nb_cache.backends.base import BaseBackend
+from nb_cache.backends.memory import MemoryBackend
+
+__all__ = ['BaseBackend', 'MemoryBackend']

nb_cache/backends/base.py

@@ -0,0 +1,186 @@
+# -*- coding: utf-8 -*-
+"""Abstract base class for cache backends.
+
+Every backend must provide both sync and async interfaces.
+"""
+import asyncio
+
+
+class BaseBackend(object):
+    """Abstract cache backend with sync and async interfaces."""
+
+    def __init__(self, **kwargs):
+        self._is_init = False
+
+    @property
+    def is_init(self):
+        return self._is_init
+
+    # --- Lifecycle ---
+
+    async def init(self):
+        self._is_init = True
+
+    def init_sync(self):
+        self._is_init = True
+
+    async def close(self):
+        self._is_init = False
+
+    def close_sync(self):
+        self._is_init = False
+
+    async def ping(self):
+        return True
+
+    def ping_sync(self):
+        return True
+
+    # --- Core GET/SET/DELETE (async) ---
+
+    async def get(self, key):
+        raise NotImplementedError
+
+    async def set(self, key, value, ttl=None):
+        raise NotImplementedError
+
+    async def delete(self, key):
+        raise NotImplementedError
+
+    async def exists(self, key):
+        raise NotImplementedError
+
+    async def expire(self, key, ttl):
+        raise NotImplementedError
+
+    async def get_expire(self, key):
+        """Return remaining TTL in seconds, or -1 if no expiry, or None if key missing."""
+        raise NotImplementedError
+
+    async def clear(self):
+        raise NotImplementedError
+
+    async def incr(self, key, amount=1):
+        raise NotImplementedError
+
+    # --- Batch operations (async) ---
+
+    async def get_many(self, *keys):
+        results = []
+        for k in keys:
+            results.append(await self.get(k))
+        return results
+
+    async def set_many(self, pairs, ttl=None):
+        for key, value in pairs.items():
+            await self.set(key, value, ttl=ttl)
+
+    async def delete_many(self, *keys):
+        for k in keys:
+            await self.delete(k)
+
+    async def delete_match(self, pattern):
+        raise NotImplementedError
+
+    # --- Scan / Match (async) ---
+
+    async def scan(self, pattern):
+        raise NotImplementedError
+
+    async def get_match(self, pattern):
+        raise NotImplementedError
+
+    async def get_keys_count(self):
+        raise NotImplementedError
+
+    async def get_size(self):
+        raise NotImplementedError
+
+    # --- Lock (async) ---
+
+    async def set_lock(self, key, ttl):
+        raise NotImplementedError
+
+    async def unlock(self, key):
+        raise NotImplementedError
+
+    async def is_locked(self, key):
+        raise NotImplementedError
+
+    # --- Set operations (async) ---
+
+    async def set_add(self, key, *values):
+        raise NotImplementedError
+
+    async def set_remove(self, key, *values):
+        raise NotImplementedError
+
+    async def set_pop(self, key, count=1):
+        raise NotImplementedError
+
+    # --- Core GET/SET/DELETE (sync) ---
+
+    def get_sync(self, key):
+        raise NotImplementedError
+
+    def set_sync(self, key, value, ttl=None):
+        raise NotImplementedError
+
+    def delete_sync(self, key):
+        raise NotImplementedError
+
+    def exists_sync(self, key):
+        raise NotImplementedError
+
+    def expire_sync(self, key, ttl):
+        raise NotImplementedError
+
+    def get_expire_sync(self, key):
+        raise NotImplementedError
+
+    def clear_sync(self):
+        raise NotImplementedError
+
+    def incr_sync(self, key, amount=1):
+        raise NotImplementedError
+
+    # --- Batch (sync) ---
+
+    def get_many_sync(self, *keys):
+        return [self.get_sync(k) for k in keys]
+
+    def set_many_sync(self, pairs, ttl=None):
+        for key, value in pairs.items():
+            self.set_sync(key, value, ttl=ttl)
+
+    def delete_many_sync(self, *keys):
+        for k in keys:
+            self.delete_sync(k)
+
+    def delete_match_sync(self, pattern):
+        raise NotImplementedError
+
+    # --- Scan (sync) ---
+
+    def scan_sync(self, pattern):
+        raise NotImplementedError
+
+    def get_match_sync(self, pattern):
+        raise NotImplementedError
+
+    def get_keys_count_sync(self):
+        raise NotImplementedError
+
+    def get_size_sync(self):
+        raise NotImplementedError
+
+    # --- Lock (sync) ---
+
+    def set_lock_sync(self, key, ttl):
+        raise NotImplementedError
+
+    def unlock_sync(self, key):
+        raise NotImplementedError
+
+    def is_locked_sync(self, key):
+        raise NotImplementedError

nb_cache/backends/dual.py

@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+"""Dual cache backend: memory (L1) + Redis (L2).
+
+Reads check memory first, then Redis on miss.
+Writes go to both memory and Redis.
+"""
+from nb_cache.backends.base import BaseBackend
+from nb_cache.backends.memory import MemoryBackend
+from nb_cache.backends.redis import RedisBackend
+from nb_cache.ttl import ttl_to_seconds
+
+
+class DualBackend(BaseBackend):
+    """Two-layer cache: fast in-memory L1 + Redis L2.
+
+    Args:
+        memory_size: Max entries for the memory layer.
+        local_ttl: Default TTL for local memory cache (seconds).
+            If set, local cache uses this TTL regardless of the outer TTL,
+            which is useful for keeping local cache short-lived.
+        url/host/port/db/password: Redis connection parameters.
+        prefix: Redis key prefix.
+    """
+
+    def __init__(self, memory_size=1000, local_ttl=None,
+                 url=None, host="localhost", port=6379, db=0,
+                 password=None, prefix="", **kwargs):
+        super(DualBackend, self).__init__(**kwargs)
+        self._local_ttl = local_ttl
+        self._memory = MemoryBackend(size=memory_size)
+        self._redis = RedisBackend(
+            url=url, host=host, port=port, db=db,
+            password=password, prefix=prefix, **kwargs,
+        )
+
+    def _local_ttl_val(self, ttl):
+        if self._local_ttl is not None:
+            return self._local_ttl
+        return ttl
+
+    # --- Lifecycle ---
+
+    async def init(self):
+        await self._memory.init()
+        await self._redis.init()
+        await super(DualBackend, self).init()
+
+    def init_sync(self):
+        self._memory.init_sync()
+        self._redis.init_sync()
+        super(DualBackend, self).init_sync()
+
+    async def close(self):
+        await self._memory.close()
+        await self._redis.close()
+        await super(DualBackend, self).close()
+
+    def close_sync(self):
+        self._memory.close_sync()
+        self._redis.close_sync()
+        super(DualBackend, self).close_sync()
+
+    async def ping(self):
+        return await self._redis.ping()
+
+    def ping_sync(self):
+        return self._redis.ping_sync()
+
+    # --- Async interface ---
+
+    async def get(self, key):
+        val = await self._memory.get(key)
+        if val is not None:
+            return val
+        val = await self._redis.get(key)
+        if val is not None:
+            local_ttl = self._local_ttl_val(None)
+            await self._memory.set(key, val, ttl=local_ttl)
+        return val
+
+    async def set(self, key, value, ttl=None):
+        await self._redis.set(key, value, ttl=ttl)
+        await self._memory.set(key, value, ttl=self._local_ttl_val(ttl))
+
+    async def delete(self, key):
+        await self._memory.delete(key)
+        return await self._redis.delete(key)
+
+    async def exists(self, key):
+        if await self._memory.exists(key):
+            return True
+        return await self._redis.exists(key)
+
+    async def expire(self, key, ttl):
+        await self._memory.expire(key, self._local_ttl_val(ttl))
+        return await self._redis.expire(key, ttl)
+
+    async def get_expire(self, key):
+        return await self._redis.get_expire(key)
+
+    async def clear(self):
+        await self._memory.clear()
+        await self._redis.clear()
+
+    async def incr(self, key, amount=1):
+        result = await self._redis.incr(key, amount)
+        self._memory.set_sync(key, result, ttl=self._local_ttl_val(None))
+        return result
+
+    async def get_many(self, *keys):
+        results = []
+        missed_keys = []
+        missed_indices = []
+        for i, k in enumerate(keys):
+            val = await self._memory.get(k)
+            results.append(val)
+            if val is None:
+                missed_keys.append(k)
+                missed_indices.append(i)
+        if missed_keys:
+            redis_vals = await self._redis.get_many(*missed_keys)
+            for idx, val in zip(missed_indices, redis_vals):
+                results[idx] = val
+                if val is not None:
+                    k = keys[idx]
+                    await self._memory.set(k, val, ttl=self._local_ttl_val(None))
+        return results
+
+    async def set_many(self, pairs, ttl=None):
+        await self._redis.set_many(pairs, ttl=ttl)
+        await self._memory.set_many(pairs, ttl=self._local_ttl_val(ttl))
+
+    async def delete_many(self, *keys):
+        await self._memory.delete_many(*keys)
+        await self._redis.delete_many(*keys)
+
+    async def delete_match(self, pattern):
+        self._memory.delete_match_sync(pattern)
+        await self._redis.delete_match(pattern)
+
+    async def scan(self, pattern):
+        return await self._redis.scan(pattern)
+
+    async def get_match(self, pattern):
+        return await self._redis.get_match(pattern)
+
+    async def get_keys_count(self):
+        return await self._redis.get_keys_count()
+
+    async def get_size(self):
+        return await self._redis.get_size()
+
+    async def set_lock(self, key, ttl):
+        return await self._redis.set_lock(key, ttl)
+
+    async def unlock(self, key):
+        return await self._redis.unlock(key)
+
+    async def is_locked(self, key):
+        return await self._redis.is_locked(key)
+
+    # --- Sync interface ---
+
+    def get_sync(self, key):
+        val = self._memory.get_sync(key)
+        if val is not None:
+            return val
+        val = self._redis.get_sync(key)
+        if val is not None:
+            local_ttl = self._local_ttl_val(None)
+            self._memory.set_sync(key, val, ttl=local_ttl)
+        return val
+
+    def set_sync(self, key, value, ttl=None):
+        self._redis.set_sync(key, value, ttl=ttl)
+        self._memory.set_sync(key, value, ttl=self._local_ttl_val(ttl))
+
+    def delete_sync(self, key):
+        self._memory.delete_sync(key)
+        return self._redis.delete_sync(key)
+
+    def exists_sync(self, key):
+        if self._memory.exists_sync(key):
+            return True
+        return self._redis.exists_sync(key)
+
+    def expire_sync(self, key, ttl):
+        self._memory.expire_sync(key, self._local_ttl_val(ttl))
+        return self._redis.expire_sync(key, ttl)
+
+    def get_expire_sync(self, key):
+        return self._redis.get_expire_sync(key)
+
+    def clear_sync(self):
+        self._memory.clear_sync()
+        self._redis.clear_sync()
+
+    def incr_sync(self, key, amount=1):
+        result = self._redis.incr_sync(key, amount)
+        self._memory.set_sync(key, result, ttl=self._local_ttl_val(None))
+        return result
+
+    def get_many_sync(self, *keys):
+        results = []
+        missed_keys = []
+        missed_indices = []
+        for i, k in enumerate(keys):
+            val = self._memory.get_sync(k)
+            results.append(val)
+            if val is None:
+                missed_keys.append(k)
+                missed_indices.append(i)
+        if missed_keys:
+            redis_vals = self._redis.get_many_sync(*missed_keys)
+            for idx, val in zip(missed_indices, redis_vals):
+                results[idx] = val
+                if val is not None:
+                    k = keys[idx]
+                    self._memory.set_sync(k, val, ttl=self._local_ttl_val(None))
+        return results
+
+    def set_many_sync(self, pairs, ttl=None):
+        self._redis.set_many_sync(pairs, ttl=ttl)
+        self._memory.set_many_sync(pairs, ttl=self._local_ttl_val(ttl))
+
+    def delete_many_sync(self, *keys):
+        self._memory.delete_many_sync(*keys)
+        self._redis.delete_many_sync(*keys)
+
+    def delete_match_sync(self, pattern):
+        self._memory.delete_match_sync(pattern)
+        self._redis.delete_match_sync(pattern)
+
+    def scan_sync(self, pattern):
+        return self._redis.scan_sync(pattern)
+
+    def get_match_sync(self, pattern):
+        return self._redis.get_match_sync(pattern)
+
+    def get_keys_count_sync(self):
+        return self._redis.get_keys_count_sync()
+
+    def get_size_sync(self):
+        return self._redis.get_size_sync()
+
+    def set_lock_sync(self, key, ttl):
+        return self._redis.set_lock_sync(key, ttl)
+
+    def unlock_sync(self, key):
+        return self._redis.unlock_sync(key)
+
+    def is_locked_sync(self, key):
+        return self._redis.is_locked_sync(key)