ddredis 0.0.1__py3-none-any.whl

ddredis/__init__.py

@@ -0,0 +1,3 @@
+from . import cache, decorators, lock
+
+__all__ = ('cache', 'decorators', 'lock')

ddredis/cache.py

@@ -0,0 +1,141 @@
+from abc import ABC
+from functools import cached_property
+from random import randint
+from typing import ClassVar, Protocol, Self, TypeVar, cast
+
+from ddutils.class_helpers import get_generic_base_argument
+from ddutils.convertors import convert_camel_case_to_snake_case
+from redis.asyncio import Redis
+
+from ddredis.decorators import suppress_redis_errors
+
+JITTER_PERCENT = 10
+
+
+class Serializable(Protocol):
+    """Protocol for objects that can be serialized/deserialized to/from JSON."""
+
+    @classmethod
+    def model_validate_json(cls, json_data: str | bytes) -> Self: ...
+
+    def model_dump_json(self) -> str: ...
+
+
+class Stringable(Protocol):
+    def __str__(self) -> str: ...
+
+
+class GenericCache[DomainT: Serializable](ABC):
+    """
+    GenericCache: An async generic caching repository for managing domain objects in Redis.
+
+    This class provides a base implementation for caching domain objects in Redis.
+    It supports CRUD operations (`get`, `create`, `update`, `delete`)
+    and uses JSON serialization/deserialization to store and retrieve data.
+
+    Domain class must implement `model_validate_json` and `model_dump_json` methods
+    (compatible with Pydantic, msgspec, or custom implementations).
+
+    Class Attributes:
+        ttl (int): Time-to-live for cache entries in seconds. Default is 5 minutes.
+        redis_client (Redis): Redis client instance.
+
+    Example Usage:
+        redis_client = Redis.from_url('redis://localhost/0')
+
+        class MyDomain(BaseModel):
+            id: int
+            name: str
+
+        class MyDomainCache(GenericCache[MyDomain]):
+            ttl = 10 * 60  # 10 minutes
+            redis_client = redis_client
+
+        cache = MyDomainCache()
+
+        domain = MyDomain(id=1, name="Test")
+        await cache.create(key=domain.id, value=domain)
+        retrieved = await cache.get(key=1)
+    """
+
+    _domain_class: ClassVar[type[Serializable]]
+
+    ttl: ClassVar[int] = 5 * 60  # 5 minutes
+    redis_client: ClassVar[Redis]
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+
+        domain_class = get_generic_base_argument(cls, GenericCache)
+        if domain_class is None or isinstance(domain_class, TypeVar):
+            raise TypeError(f'{cls.__name__} must specify domain type: class {cls.__name__}(GenericCache[YourDomain])')
+
+        cls._domain_class = domain_class
+
+    @cached_property
+    def _key_prefix(self) -> str:
+        return convert_camel_case_to_snake_case(self._domain_class.__name__)
+
+    @cached_property
+    def _jitter(self) -> int:
+        return self.ttl * JITTER_PERCENT // 100
+
+    def _generate_key(self, key: Stringable) -> str:
+        """Generates a Redis key for the given identifier with the domain-specific prefix."""
+        return f':{self._key_prefix}:{key!s}'
+
+    def _generate_ttl(self) -> int:
+        """Generates a TTL value with jitter."""
+        return self.ttl + randint(-self._jitter, self._jitter)
+
+    async def _get(self, key: str) -> DomainT | None:
+        """Reads and deserializes a domain object by its already-prefixed Redis key."""
+        cached_data = await self.redis_client.get(key)
+        if not cached_data:
+            return None
+        try:
+            return cast('DomainT', self._domain_class.model_validate_json(cached_data))
+        except Exception:  # noqa: BLE001
+            return None
+
+    @suppress_redis_errors
+    async def get(self, key: Stringable) -> DomainT | None:
+        """Retrieves and deserializes a domain object from the cache by its key."""
+        return await self._get(self._generate_key(key))
+
+    @suppress_redis_errors
+    async def create(self, key: Stringable, value: DomainT) -> None:
+        """Caches a new domain object or overwrites an existing one. Sets a TTL for the entry."""
+        _key = self._generate_key(key)
+        await self.redis_client.set(_key, value.model_dump_json(), ex=self._generate_ttl())
+
+    @suppress_redis_errors
+    async def update(self, key: Stringable, value: DomainT) -> None:
+        """Updates a domain object in the cache. Alias for `create`."""
+        await self.create(key=key, value=value)
+
+    @suppress_redis_errors
+    async def delete(self, key: Stringable) -> None:
+        """Removes a domain object from the cache by its key."""
+        await self.redis_client.delete(self._generate_key(key))
+
+    @suppress_redis_errors
+    async def get_list(self, key_prefix: Stringable) -> list[DomainT]:
+        """Returns all cached domain objects whose keys start with the given prefix."""
+        pattern = f'{self._generate_key(key_prefix)}*'
+        result: list[DomainT] = []
+        async for redis_key in self.redis_client.scan_iter(match=pattern):
+            item = await self._get(redis_key)
+            if item is not None:
+                result.append(item)
+        return result
+
+    @suppress_redis_errors
+    async def delete_by_filters(self, key_prefix: Stringable) -> None:
+        """Removes all cached domain objects whose keys start with the given prefix."""
+        pattern = f'{self._generate_key(key_prefix)}*'
+        async for redis_key in self.redis_client.scan_iter(match=pattern):
+            await self.redis_client.delete(redis_key)
+
+
+__all__ = ('GenericCache', 'Serializable', 'Stringable')

ddredis/decorators.py

@@ -0,0 +1,21 @@
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any
+
+from redis.exceptions import RedisError
+
+
+def suppress_redis_errors[T](func: Callable[..., Awaitable[T]]) -> Callable[..., Awaitable[T | None]]:
+    """Decorator to suppress Redis exceptions and return None on failure."""
+
+    @wraps(func)
+    async def wrapper(*args: Any, **kwargs: Any) -> T | None:
+        try:
+            return await func(*args, **kwargs)
+        except RedisError:
+            return None
+
+    return wrapper
+
+
+__all__ = ('suppress_redis_errors',)

ddredis/lock.py

@@ -0,0 +1,65 @@
+import contextlib
+from typing import Self
+
+from redis.asyncio import Redis
+from redis.asyncio.lock import Lock, LockNotOwnedError
+
+
+class AlreadyAcquiredError(Exception): ...
+
+
+class RedisLock:
+    """
+    Distributed lock backed by Redis (`SET NX PX` + Lua release).
+
+    Caveat: `timeout` is the Redis-side TTL of the key — not a client-side cancellation
+    timer. If the protected code runs longer than `timeout`, Redis silently removes the
+    key and a competing caller can acquire the same lock and execute in parallel,
+    violating mutual exclusion. The original code keeps running unaware. `release()`
+    swallows `LockNotOwnedError` for this case, so the cleanup is silent — but the
+    invariant has already been broken upstream.
+
+    To avoid this, either pick a `timeout` that comfortably exceeds the worst-case
+    runtime of the block, or call `extend()` periodically (heartbeat) for long
+    operations whose duration is hard to predict.
+    """
+
+    def __init__(self, redis_client: Redis, key: str, timeout: float = 10.0, blocking: bool = False):
+        blocking_timeout = timeout if blocking else None
+        self.timeout = timeout
+        self.lock = Lock(
+            redis=redis_client,
+            name=key,
+            timeout=timeout,
+            blocking=blocking,
+            blocking_timeout=blocking_timeout,
+            thread_local=False,
+        )
+
+    async def acquire(self) -> None:
+        acquired = await self.lock.acquire()
+
+        if not acquired:
+            raise AlreadyAcquiredError('Lock is already acquired')
+
+    async def release(self) -> None:
+        with contextlib.suppress(LockNotOwnedError):
+            await self.lock.release()
+
+    async def extend(self) -> None:
+        # `replace_ttl=True` because every caller means this as a heartbeat: the lock should
+        # outlive the holder by `timeout`, counted from now. redis-py's default ADDS to the
+        # remaining TTL, so a long-lived holder beating steadily would push the expiry further
+        # out with every beat — and a lock whose holder is killed would then sit unreleased for
+        # as long as it had been beating.
+        await self.lock.extend(self.timeout, replace_ttl=True)
+
+    async def __aenter__(self) -> Self:
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.release()
+
+
+__all__ = ('AlreadyAcquiredError', 'RedisLock')

ddredis-0.0.1.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: ddredis
+Version: 0.0.1
+Summary: Redis helpers: generic JSON cache and distributed lock
+Keywords: python,redis,cache,lock,ddredis
+Author: davyddd
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: redis>=5.0,<9
+Requires-Dist: ddutils>=0.2.2,<0.3.0
+Requires-Python: >=3.12, <3.15
+Project-URL: Repository, https://github.com/davyddd/ddredis
+Description-Content-Type: text/markdown
+
+# ddredis
+
+[![pypi](https://img.shields.io/pypi/v/ddredis.svg)](https://pypi.python.org/pypi/ddredis)
+[![downloads](https://static.pepy.tech/badge/ddredis/month)](https://pepy.tech/project/ddredis)
+[![versions](https://img.shields.io/pypi/pyversions/ddredis.svg)](https://github.com/davyddd/ddredis)
+[![codecov](https://codecov.io/gh/davyddd/ddredis/branch/main/graph/badge.svg)](https://app.codecov.io/github/davyddd/ddredis)
+[![license](https://img.shields.io/github/license/davyddd/ddredis.svg)](https://github.com/davyddd/ddredis/blob/main/LICENSE)
+
+Redis helpers: generic JSON cache and distributed lock
+
+## Installation
+
+Install the library using pip:
+```bash
+pip install ddredis
+```
+
+## Development
+
+The project runs entirely in Docker. Requires Docker and [Fabric](https://www.fabfile.org/) on the host:
+
+```bash
+fab build      # build the dev image
+fab tests      # run pytest
+fab linters    # run ruff (with --fix), ty and complexipy
+fab shell      # IPython inside the container
+fab bash       # bash inside the container
+```
+
+This project was generated from [dd-lib-stub](https://github.com/davyddd/dd-lib-stub);
+run `copier update` to pull in template updates.
+
+## GenericCache
+
+Caches domain objects in Redis as JSON. The domain class must provide `model_validate_json` and
+`model_dump_json` (pydantic models do), keys are prefixed with the snake-cased domain name, every entry gets
+the class `ttl` with ±10% jitter so a burst of writes does not expire at once, and Redis errors turn into
+"not found" instead of failing the caller.
+
+```python
+from typing import ClassVar
+
+from pydantic import BaseModel
+from redis.asyncio import Redis
+
+from ddredis.cache import GenericCache
+
+redis_client = Redis.from_url('redis://localhost/0')
+
+
+class Profile(BaseModel):
+    profile_id: int
+    name: str
+
+
+class ProfileCache(GenericCache[Profile]):
+    ttl = 10 * 60  # seconds
+    redis_client: ClassVar[Redis] = redis_client
+
+
+cache = ProfileCache()
+
+await cache.create(key=1, value=Profile(profile_id=1, name='John'))   # SET :profile:1 ... EX ttl±10%
+profile = await cache.get(key=1)                                       # Profile | None
+await cache.update(key=1, value=profile)                               # alias for create
+await cache.delete(key=1)
+
+await cache.get_list(key_prefix='team-a')                              # every :profile:team-a* entry
+await cache.delete_by_filters(key_prefix='team-a')
+```
+
+Redis errors are swallowed on purpose: for a cache, "unavailable" and "miss" lead to the same fallback. Do
+not use the cache for state where `None` has a meaning of its own. Transient failures (a worker that was just
+reloaded, a dropped connection) belong to the client, not to the cache: redis-py retries the errors listed in
+`retry_on_error` with its default `Retry` (3 attempts, exponential backoff with jitter), so a production client
+looks like this:
+
+```python
+from redis.asyncio import Redis
+from redis.exceptions import ConnectionError, TimeoutError
+
+redis_client = Redis.from_url(
+    'redis://localhost/0',
+    max_connections=20,
+    socket_connect_timeout=5,
+    socket_timeout=1,
+    retry_on_error=[ConnectionError, TimeoutError],
+    decode_responses=True,
+)
+```
+
+## RedisLock
+
+Distributed lock on `SET NX PX` with a Lua release (redis-py's `Lock`, `thread_local=False`). Acquiring a
+held lock raises `AlreadyAcquiredError` unless `blocking=True`, in which case it waits up to `timeout`.
+
+```python
+from ddredis.lock import AlreadyAcquiredError, RedisLock
+
+try:
+    async with RedisLock(redis_client, 'sync-profiles', timeout=30):
+        await sync_profiles()
+except AlreadyAcquiredError:
+    pass  # another worker is on it
+```
+
+`timeout` is the Redis-side TTL of the key, not a client-side cancellation: if the block runs longer, Redis
+drops the key and a competitor may enter while the first holder is still running. Pick a timeout that
+comfortably exceeds the worst-case runtime, or call `extend()` periodically as a heartbeat. `extend()`
+replaces the TTL with the full `timeout` counted from now rather than adding to the remaining time, so a
+long-lived holder beating steadily never pushes its expiry further out. `release()` tolerates a lock that
+already expired.
+
+## suppress_redis_errors
+
+Decorator for async functions: `RedisError` subclasses become a `None` result, everything else propagates.
+`GenericCache` methods use it; apply it to your own Redis reads that should degrade instead of failing.
+

ddredis-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+ddredis/__init__.py,sha256=Lo082hCxyyT6OBJ4HQS5JkZ27KFIJsb6oh0uE1KA5FY,81
+ddredis/cache.py,sha256=GhbrH5mJVkero5d6yUWYyWcqgl3xldhHgd8wdTiuQY8,5266
+ddredis/decorators.py,sha256=tKnh3Hmh6qPkKp5dXu6WXAbpzxX5FuiXH8MGVQ2Tj0Q,572
+ddredis/lock.py,sha256=5SiySSHnGCf2NfwLZNKvMrLCVceHUsc-2Id1G75j20Q,2449
+ddredis/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ddredis-0.0.1.dist-info/licenses/LICENSE,sha256=_DkcY418J4TyqQWxa0QjLzg1jCl1NiR-XE_UyK-Rv6g,1070
+ddredis-0.0.1.dist-info/WHEEL,sha256=lrO5MD1WVAWzcbNy_L2BwtfPrcM3KfUFpbKYXLkJX4A,80
+ddredis-0.0.1.dist-info/METADATA,sha256=JXcUxjeUHVPbKgydPOMnkDuYYQ26uqEuVSEi-LJzWKc,5093
+ddredis-0.0.1.dist-info/RECORD,,

ddredis-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.1
+Root-Is-Purelib: true
+Tag: py3-none-any

ddredis-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Davydov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.