redis-xsync 1.0.1__py3-none-any.whl

redis_xsync/__init__.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""
+@File    : __init__.py
+@Author  : Jay
+@Date    : 2025/3/16 14:37
+@Desc    : Redis client registry and default instance setup
+"""
+import asyncio
+
+# Set Windows event loop policy to avoid runtime errors on Windows
+asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+from collections import defaultdict
+from typing import Optional, Union
+
+from .rxcore import RedisXsync
+
+# Registry of Redis instances keyed by label
+_redis_registry: defaultdict[str, RedisXsync] = defaultdict(RedisXsync)
+
+# Global default Redis instance
+redisXsync: Optional[RedisXsync] = RedisXsync(host="localhost", port=6379, db=-1)
+
+
+class RedisNotInstantiatedError(Exception):
+    """Raised when trying to access a Redis instance that hasn't been registered."""
+    pass
+
+
+def register_redis(label: str, host: str = None, port: int = None, db: Union[str, int] = None,
+                   password: Optional[str] = None, decode_responses: bool = None, **kwargs) -> RedisXsync:
+    """Register a Redis instance in the global registry.
+
+    If no global default exists, the first registered instance becomes the default.
+
+    Args:
+        label (str): Unique identifier for the Redis instance.
+        host (str, optional): Redis server host.
+        port (int, optional): Redis server port.
+        db (int|str, optional): Redis database index.
+        password (str, optional): Redis password.
+        decode_responses (bool, optional): Whether to decode byte responses.
+        **kwargs: Additional Redis configuration parameters.
+
+    Returns:
+        RedisXsync: The registered Redis client instance.
+    """
+    global redisXsync
+    rx = RedisXsync(
+        host=host, port=port,
+        db=db, password=password,
+        decode_responses=decode_responses,
+        **kwargs
+    )
+    # Set the first registered instance as the default if none exists
+    if not _redis_registry:
+        redisXsync.rxs = rx.rxs
+    _redis_registry.setdefault(label, rx)
+    return _redis_registry[label]
+
+
+def resolve_redis(label: str = None) -> RedisXsync:
+    """Resolve a registered Redis instance by label.
+
+    Args:
+        label (str, optional): The label of the Redis instance. If None, returns the first registered instance.
+
+    Returns:
+        RedisXsync: The resolved Redis client instance.
+
+    Raises:
+        RedisNotInstantiatedError: If no instance with the given label is registered.
+    """
+    if label is None and _redis_registry:
+        return next(iter(_redis_registry.values()))
+    r = _redis_registry.get(label)
+    if r:
+        return r
+    raise RedisNotInstantiatedError(f"No Redis instance registered with label '{label}'")
+
+
+__all__ = ["register_redis", "resolve_redis", "RedisXsync", "redisXsync"]

redis_xsync/awaitable/__init__.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""
+@File    : __init__.py
+@Author  : Jay
+@Date    : 2026/3/19 18:01
+@Desc    : Utilities to detect synchronous vs asynchronous call context
+         and to decorate async functions to fallback to sync implementations.
+"""
+import inspect
+import sys
+from functools import wraps
+from typing import Callable, Any
+
+# Flags from code objects that indicate coroutine behavior
+_CO_FROM_COROUTINE = (
+        inspect.CO_COROUTINE
+        | inspect.CO_ITERABLE_COROUTINE
+        | inspect.CO_ASYNC_GENERATOR
+)
+
+
+def is_coroutine_context(level: int = 2) -> bool:
+    """Determine if the current call context is asynchronous (coroutine).
+
+    Args:
+        level (int): Stack level to inspect (default 2). Increase if called from wrapper functions.
+
+    Returns:
+        bool: True if the current frame is part of a coroutine context, False if synchronous.
+    """
+    frame = sys._getframe(level)
+    f_code = frame.f_code
+
+    # Check if the code object has coroutine flags
+    if f_code.co_flags & _CO_FROM_COROUTINE:
+        return True
+
+    # Handle nested "<...>" function wrappers (like decorators)
+    if f_code.co_flags & inspect.CO_NESTED and f_code.co_name[0] == '<':
+        return is_coroutine_context(level + 2)
+
+    return False
+
+
+def awaitable(sync_func: Callable) -> Callable:
+    """Decorator for async functions to use a synchronous fallback when called from sync context.
+
+    Usage:
+        def foo_sync(x, y): ...
+
+        @awaitable(foo_sync)
+        async def foo_async(x, y): ...
+
+    Args:
+        sync_func (Callable): Synchronous implementation of the async function.
+
+    Returns:
+        Callable: Decorated async function that uses `sync_func` if called synchronously.
+    """
+
+    def decorator(async_func: Callable) -> Callable:
+        # Signature check to ensure sync/async match
+        sig_sync = inspect.signature(sync_func)
+        sig_async = inspect.signature(async_func)
+        if sig_sync != sig_async:
+            raise TypeError(
+                f"{sync_func.__name__} and async {async_func.__name__} signatures differ:\n"
+                f"  sync: {sig_sync}\n"
+                f"  async: {sig_async}"
+            )
+
+        @wraps(async_func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # If currently inside a coroutine, run async function
+            if is_coroutine_context():
+                return async_func(*args, **kwargs)
+
+            # Otherwise, run synchronous version
+            result = sync_func(*args, **kwargs)
+            if inspect.iscoroutine(result):
+                raise RuntimeError(
+                    f"Synchronous function {sync_func.__name__} returned a coroutine object. "
+                    f"Ensure it is a true synchronous implementation."
+                )
+            return result
+
+        # Attach references for introspection
+        wrapper._sync_func = sync_func
+        wrapper._async_func = async_func
+        wrapper._awaitable = True
+        return wrapper
+
+    return decorator
+
+
+__all__ = ["awaitable", "is_coroutine_context"]
+
+if __name__ == '__main__':
+    # Demonstration of `awaitable` decorator usage
+    class Limited:
+        def _ask_available_container_sync(self, quantity):
+            """Synchronous fallback implementation."""
+            return "sync-"
+
+        @awaitable(_ask_available_container_sync)
+        async def ask_available_container(self, quantity):
+            """Async implementation."""
+            return "async+"
+
+
+    lt = Limited()
+
+    # Synchronous call
+    res_sync = lt.ask_available_container(1)
+    print("Sync result:", res_sync)
+
+    # Asynchronous call
+    import asyncio
+
+
+    async def main():
+        res_async = await lt.ask_available_container(2)
+        print("Async result:", res_async)
+
+
+    asyncio.run(main())

redis_xsync/distributed_lock.py

@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""
+@File    : distributed_lock.py
+@Author  : Jay
+@Date    : 2026/3/18 17:47
+@Desc    : Redis connection pool and distributed lock implementation
+"""
+import asyncio
+import time
+import uuid
+
+_ACQUIRE_LUA = """
+local ttl_ms = tonumber(ARGV[#ARGV])
+for i=1,#KEYS do
+    if redis.call('exists', KEYS[i]) == 1 then
+        return 0
+    end
+    redis.call('set', KEYS[i], ARGV[i], 'PX', ttl_ms)
+end
+return 1
+"""
+_RELEASE_LUA = """
+for i=1,#KEYS do
+  if redis.call('get', KEYS[i]) == ARGV[i] then
+    redis.call('del', KEYS[i])
+  end
+end
+return 1
+"""
+
+
+# Distributed lock class, use `aioredlock` for cluster-wide locks
+class AsyncRedisAtomicMultiLock:
+    """Implements a Redis-based atomic multi-key lock with optional blocking behavior."""
+
+    def __init__(
+            self,
+            *keys: str,
+            redis_xsync,
+            redis_db,
+            ttl_ms: int = 5000,
+            blocking: bool = False,
+            blocking_timeout: int = 5,
+            sleep: float = 0.3
+    ):
+        """Initialize the atomic multi-key lock.
+
+        Args:
+            *keys (str): Redis keys to lock, can pass multiple keys.
+            redis_xsync: Redis client factory supporting sync/async context.
+            redis_db: Redis database number.
+            ttl_ms (int): Lock timeout in milliseconds.
+            blocking (bool): If True, wait until lock is acquired when already locked.
+            blocking_timeout (int): Maximum blocking wait time in seconds.
+            sleep (float): Sleep interval between retries when blocking.
+        """
+        self.redis_xsync = redis_xsync
+        self.redis_db = redis_db
+        self.keys = list(keys)
+        self.ttl_ms = int(ttl_ms)
+        self.container = list(map(lambda _: uuid.uuid4().hex, keys))  # Unique lock values
+        self.acquired = False
+
+        self.blocking = blocking
+        self.blocking_timeout = blocking_timeout
+        self.sleep = sleep
+
+    # <editor-fold desc="Distributed lock: async implementation">
+    async def _async_with_client(self, script: str, keys, *args):
+        """Helper to run Lua scripts asynchronously against Redis.
+
+        Args:
+            script (str): Lua script to execute.
+            keys (list): List of Redis keys.
+            *args: Arguments for the Lua script.
+
+        Returns:
+            bool: True if Lua script returned success (1), False otherwise.
+        """
+        async with self.redis_xsync(db=self.redis_db) as redis:
+            return (await redis.eval(script, len(keys), *keys, *args)) == 1
+
+    async def async_acquire(self) -> bool:
+        """Asynchronously acquire the lock.
+
+        Returns:
+            bool: True if lock acquired successfully, False otherwise.
+        """
+        argv = [*self.container, str(self.ttl_ms)]
+
+        async def try_once():
+            return await self._async_with_client(_ACQUIRE_LUA, self.keys, *argv)
+
+        if not self.blocking:
+            self.acquired = await try_once()
+            return self.acquired
+
+        end_time = asyncio.get_event_loop().time() + self.blocking_timeout
+        while True:
+            if await try_once():
+                self.acquired = True
+                return True
+            if asyncio.get_event_loop().time() > end_time:
+                return False
+            await asyncio.sleep(self.sleep)
+
+    async def async_release(self) -> None:
+        """Asynchronously release the lock, only if held by this instance."""
+        try:
+            await self._async_with_client(_RELEASE_LUA, self.keys, *self.container)
+        finally:
+            self.acquired = False
+
+    async def __aenter__(self):
+        """Async context manager entry.
+
+        Raises:
+            TimeoutError: If lock cannot be acquired within timeout.
+
+        Returns:
+            AsyncRedisAtomicMultiLock: self
+        """
+        ok = await self.async_acquire()
+        if not ok:
+            raise TimeoutError("Failed to acquire lock within timeout")
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        """Async context manager exit."""
+        await self.async_release()
+
+    # </editor-fold>
+
+    # <editor-fold desc="Distributed lock: sync implementation">
+    def _sync_with_client(self, script: str, keys, *args) -> bool:
+        """Helper to run Lua scripts synchronously against Redis.
+
+        Args:
+            script (str): Lua script to execute.
+            keys (list): List of Redis keys.
+            *args: Arguments for the Lua script.
+
+        Returns:
+            bool: True if Lua script returned success (1), False otherwise.
+        """
+        with self.redis_xsync(db=self.redis_db) as redis:
+            return int(redis.eval(script, len(keys), *keys, *args)) == 1
+
+    def sync_acquire(self) -> bool:
+        """Synchronously acquire the lock.
+
+        Returns:
+            bool: True if lock acquired successfully, False otherwise.
+        """
+        argv = [*self.container, str(self.ttl_ms)]
+
+        def try_once():
+            return self._sync_with_client(_ACQUIRE_LUA, self.keys, *argv)
+
+        if not self.blocking:
+            self.acquired = try_once()
+            return self.acquired
+
+        end_time = time.time() + self.blocking_timeout
+        while True:
+            if try_once():
+                self.acquired = True
+                return True
+            if time.time() > end_time:
+                return False
+            time.sleep(self.sleep)
+
+    def sync_release(self) -> None:
+        """Synchronously release the lock."""
+        try:
+            self._sync_with_client(_RELEASE_LUA, self.keys, *self.container)
+        finally:
+            self.acquired = False
+
+    def __enter__(self):
+        """Sync context manager entry.
+
+        Raises:
+            TimeoutError: If lock cannot be acquired within timeout.
+
+        Returns:
+            AsyncRedisAtomicMultiLock: self
+        """
+        ok = self.sync_acquire()
+        if not ok:
+            raise TimeoutError(
+                f"Failed to acquire lock on keys {self.keys} in {self.blocking_timeout}s"
+            )
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Sync context manager exit."""
+        self.sync_release()
+    # </editor-fold>
+
+
+__all__ = ["AsyncRedisAtomicMultiLock"]