coredis-utils 0.1.0__tar.gz

coredis_utils-0.1.0/.gitignore

@@ -0,0 +1,112 @@
+.DS_Store
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+tmp.py
+*.override.yml
+
+# C extensions
+*.so
+data/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mypy
+.mypy_cache/
+
+# idea
+.idea
+*.iml
+*.ipr
+
+.vscode/
+
+main.py

coredis_utils-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tastyware
+
+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.

coredis_utils-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: coredis-utils
+Version: 0.1.0
+Summary: A collection of helpful utilities for coredis.
+Project-URL: Homepage, https://github.com/tastyware/coredis-utils
+Project-URL: Funding, https://github.com/sponsors/tastyware
+Project-URL: Source, https://github.com/tastyware/coredis-utils
+Project-URL: Changelog, https://github.com/tastyware/coredis-utils/releases
+Author-email: Graeme Holliday <graeme@tastyware.dev>
+License: MIT License
+        
+        Copyright (c) 2026 tastyware
+        
+        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.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AnyIO
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Framework :: Trio
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: coredis>=6.6.1
+Description-Content-Type: text/markdown
+
+[![PyPI](https://img.shields.io/pypi/v/coredis-utils)](https://pypi.org/project/coredis-utils)
+[![Downloads](https://static.pepy.tech/badge/coredis-utils)](https://pepy.tech/project/coredis-utils)
+[![Release](https://img.shields.io/github/v/release/tastyware/coredis-utils?label=release%20notes)](https://github.com/tastyware/coredis-utils/releases)
+
+# coredis-utils
+
+A collection of helpful utilities for [coredis](https://coredis.readthedocs.io/en/latest/).
+
+## Features
+
+- Caching decorator with thundering herd protection and error caching
+- Idempotency keys
+- Fixed-window rate limiting
+
+## Installation
+
+```console
+$ pip install coredis-utils
+```
+
+## Getting started
+
+First, create a `CoredisUtils` object wrapping a `coredis.Redis` instance:
+
+```python
+from coredis import Redis
+from coredis_utils import CoredisUtils
+
+client = Redis(...)
+utils = CoredisUtils(client)
+```
+
+Caching is implemented with a decorator:
+
+```python
+@utils.cached(ttl=60)
+async def my_task() -> int: ...
+```
+
+Idempotency uses a simple check:
+
+```python
+if await utils.idempotent("my-key", ttl=60):
+    ...  # code in this block can only run once
+```
+
+Rate limiting is similar:
+
+```python
+for _ in range(15):
+    print(await utils.limit("my-ip-addr", 10, 1))  # limit to 10/second
+```
+
+```python
+True
+True
+True
+True
+True
+True
+True
+True
+True
+True
+False
+False
+False
+False
+False
+```

coredis_utils-0.1.0/README.md

@@ -0,0 +1,70 @@
+[![PyPI](https://img.shields.io/pypi/v/coredis-utils)](https://pypi.org/project/coredis-utils)
+[![Downloads](https://static.pepy.tech/badge/coredis-utils)](https://pepy.tech/project/coredis-utils)
+[![Release](https://img.shields.io/github/v/release/tastyware/coredis-utils?label=release%20notes)](https://github.com/tastyware/coredis-utils/releases)
+
+# coredis-utils
+
+A collection of helpful utilities for [coredis](https://coredis.readthedocs.io/en/latest/).
+
+## Features
+
+- Caching decorator with thundering herd protection and error caching
+- Idempotency keys
+- Fixed-window rate limiting
+
+## Installation
+
+```console
+$ pip install coredis-utils
+```
+
+## Getting started
+
+First, create a `CoredisUtils` object wrapping a `coredis.Redis` instance:
+
+```python
+from coredis import Redis
+from coredis_utils import CoredisUtils
+
+client = Redis(...)
+utils = CoredisUtils(client)
+```
+
+Caching is implemented with a decorator:
+
+```python
+@utils.cached(ttl=60)
+async def my_task() -> int: ...
+```
+
+Idempotency uses a simple check:
+
+```python
+if await utils.idempotent("my-key", ttl=60):
+    ...  # code in this block can only run once
+```
+
+Rate limiting is similar:
+
+```python
+for _ in range(15):
+    print(await utils.limit("my-ip-addr", 10, 1))  # limit to 10/second
+```
+
+```python
+True
+True
+True
+True
+True
+True
+True
+True
+True
+True
+False
+False
+False
+False
+False
+```

coredis_utils-0.1.0/coredis_utils/__init__.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import hmac
+import inspect
+import pickle
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import timedelta
+from functools import wraps
+from hashlib import sha256
+from typing import Any, AnyStr, Generic, ParamSpec, TypeVar, overload
+
+from anyio import sleep
+from coredis import PureToken, Redis, RedisCluster
+from coredis.commands import CommandRequest
+from coredis.typing import KeyT
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+VERSION = "0.1.0"
+LIMITER_SCRIPT = """
+local val = redis.call('incr', KEYS[1])
+if val == 1 then
+  redis.call('expire', KEYS[1], ARGV[1])
+end
+return val
+"""
+__version__ = VERSION
+
+
+def _limit(key: KeyT, period: int) -> CommandRequest[int]: ...
+
+
+def _make_cache_key(
+    prefix: str,
+    fn: Callable[..., Any],
+    signature: inspect.Signature,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> str:
+    bound = signature.bind(*args, **kwargs)
+    bound.apply_defaults()
+    canonical = pickle.dumps(tuple(bound.arguments.items()))
+    digest = sha256(canonical).hexdigest()[:16]
+    return f"{prefix}cache:{fn.__module__}.{fn.__qualname__}:{digest}"
+
+
+def _ttl_seconds(ttl: timedelta | int) -> int:
+    if isinstance(ttl, timedelta):
+        return round(ttl.total_seconds())
+    return ttl
+
+
+# cache envelopes to distinguish a stored value from a stored error
+@dataclass(slots=True, frozen=True)
+class _Ok:
+    value: Any
+
+
+@dataclass(slots=True, frozen=True)
+class _Err:
+    exc: BaseException
+
+
+class CoredisUtils(Generic[AnyStr]):
+    """
+    Wraps a coredis client to provide additional functionality.
+
+    :param client: basic or cluster client to use
+    :param prefix: prefix for all keys used in Redis
+    :param ttl: default TTL for cached results/idempotency keys, defaults to 5 minutes
+    :param signing_secret:
+        if provided, used to sign results cached in Redis, which improves security since
+        serialization uses pickle. To generate a key, try: `secrets.token_urlsafe(32)`
+    """
+
+    __slots__ = ("_client", "_limit", "prefix", "signing_secret", "ttl")
+
+    @overload
+    def __init__(
+        self: CoredisUtils[bytes],
+        client: Redis[bytes] | RedisCluster[bytes],
+        *,
+        prefix: str | None = ...,
+        ttl: timedelta | int | None = ...,
+        signing_secret: str | None = ...,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: CoredisUtils[str],
+        client: Redis[str] | RedisCluster[str],
+        *,
+        prefix: str | None = ...,
+        ttl: timedelta | int | None = ...,
+        signing_secret: str | None = ...,
+    ) -> None: ...
+
+    def __init__(
+        self: CoredisUtils[Any],
+        client: Redis[Any] | RedisCluster[Any],
+        *,
+        prefix: str | None = "coredis-utils",
+        ttl: timedelta | int | None = 300,
+        signing_secret: str | None = None,
+    ) -> None:
+        # Redis connection
+        self._client = client
+        self.prefix = prefix + ":" if prefix else ""
+        self.ttl = ttl
+        self.signing_secret = signing_secret.encode() if signing_secret else None
+        # coredis FFI stubs for Lua script
+        self._limit = client.register_script(LIMITER_SCRIPT).wraps()(_limit)
+
+    async def idempotent(self, key: str, ttl: timedelta | int | None = 60) -> bool:
+        """
+        Shields code from being run multiple times.
+
+        :param key: idempotency key to use
+        :param ttl: how long to prevent duplicate runs, defaults to 1 minute
+        """
+        ttl = ttl or self.ttl
+        return await self._client.set(
+            f"{self.prefix}idempotent:{key}", 1, condition=PureToken.NX, ex=ttl
+        )
+
+    async def limit(self, key: str, limit: int, period: timedelta | int) -> bool:
+        """
+        Limits the number of successful calls per period to the given number using a
+        fixed-window rate limiting algorithm.
+
+        :param key: unique identifier, usually some combination of user/IP/route
+        :param limit: maximum number of calls that can succeed per period
+        :param period: duration of window before more calls can succeed
+        """
+        count = await self._limit(f"{self.prefix}limit:{key}", _ttl_seconds(period))
+        return count <= limit
+
+    def _serialize(self, data: Any) -> str | bytes:
+        try:
+            serialized = pickle.dumps(data)
+        except Exception as e:
+            raise RuntimeError(f"Failed to serialize data: {data}") from e
+        if self.signing_secret:
+            serialized += hmac.digest(self.signing_secret, serialized, "sha256")
+        return serialized
+
+    def _deserialize(self, data: Any) -> Any:
+        if self.signing_secret:
+            data_bytes, signature = data[:-32], data[-32:]
+            verify = hmac.digest(self.signing_secret, data_bytes, "sha256")
+            if not hmac.compare_digest(signature, verify):
+                raise RuntimeError("Invalid signature for task data!")
+            data = data_bytes
+        try:
+            return pickle.loads(data)
+        except Exception as e:
+            raise RuntimeError(f"Failed to deserialize data: {data}") from e
+
+    async def _try_read(self, key: str) -> _Ok | None:
+        raw = await self._client.get(key)
+        if raw is not None:
+            val = self._deserialize(raw)
+            if isinstance(val, _Err):
+                raise val.exc
+            if isinstance(val, _Ok):
+                return val
+
+    @overload
+    def cached(self, fn: Callable[P, Awaitable[R]], /) -> Callable[P, Awaitable[R]]: ...
+
+    @overload
+    def cached(
+        self,
+        *,
+        ttl: timedelta | int | None = ...,
+        error_ttl: timedelta | int | None = ...,
+        lock_timeout: timedelta | int = ...,
+    ) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]: ...
+
+    def cached(
+        self,
+        fn: Callable[P, Awaitable[R]] | None = None,
+        *,
+        ttl: timedelta | int | None = None,
+        error_ttl: timedelta | int | None = None,
+        lock_timeout: timedelta | int = 60,
+    ) -> Any:
+        """
+        Cache the function's results in Redis. Uses a lock to implement "singleflight",
+        protecting against thundering herds.
+
+        :param ttl: duration to cache results, defaults to `cache_ttl`
+        :param error_ttl:
+            duration to cache errors, defaults to `cache_ttl`, 0 means disabled
+        :param lock_timeout: TTL of the stampede protection lock, defaults to 1 minute
+        """
+        ttl = ttl or self.ttl
+        error_ttl = error_ttl if error_ttl is not None else (self.ttl or 0)
+
+        def decorator(_fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+            sig = inspect.signature(_fn)
+
+            @wraps(_fn)
+            async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                key = _make_cache_key(self.prefix, _fn, sig, args, kwargs)
+                # fast path: cache hit
+                if res := await self._try_read(key):
+                    return res.value
+                # slow path: add lock for stampede protection
+                lock = self._client.lock(
+                    f"{self.prefix}lock:{key}",
+                    timeout=_ttl_seconds(lock_timeout),
+                    blocking=False,
+                )
+                if await lock.acquire():
+                    try:
+                        if res := await self._try_read(key):
+                            return res.value
+                        value = await _fn(*args, **kwargs)
+                        await self._client.set(key, self._serialize(_Ok(value)), ex=ttl)
+                        return value
+                    except Exception as e:
+                        if error_ttl != 0:
+                            await self._client.set(
+                                key, self._serialize(_Err(exc=e)), ex=error_ttl
+                            )
+                        raise
+                    finally:
+                        await lock.release()
+                # wait for leader's result by polling the cache
+                deadline = time.monotonic() + _ttl_seconds(lock_timeout)
+                sleep_time = 0.005  # 5ms initial backoff
+                while time.monotonic() < deadline:
+                    await sleep(sleep_time)
+                    if res := await self._try_read(key):
+                        return res.value
+                    sleep_time = min(sleep_time * 2, 0.1)  # capped exponential backoff
+                # leader didn't complete in time, just run ourselves
+                return await _fn(*args, **kwargs)
+
+            return wrapper
+
+        if fn is None:
+            return decorator
+        return decorator(fn)
+
+
+__all__ = ["CoredisUtils"]

coredis_utils-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "coredis_utils/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+include = ["coredis_utils/**/*"]
+exclude = ["**/__pycache__/**"]
+
+[tool.hatch.build.targets.sdist]
+include = ["coredis_utils/**/*"]
+exclude = ["**/__pycache__/**"]
+
+[project]
+name = "coredis-utils"
+description = "A collection of helpful utilities for coredis."
+readme = "README.md"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Framework :: AsyncIO",
+    "Framework :: AnyIO",
+    "Framework :: Django",
+    "Framework :: FastAPI",
+    "Framework :: Flask",
+    "Framework :: Trio",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: Unix",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Clustering",
+    "Topic :: System :: Distributed Computing",
+    "Topic :: System :: Monitoring",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+license = {file = "LICENSE"}
+authors = [
+    { name = "Graeme Holliday", email = "graeme@tastyware.dev" }
+]
+dependencies = [
+    "coredis>=6.6.1",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/tastyware/coredis-utils"
+Funding = "https://github.com/sponsors/tastyware"
+Source = "https://github.com/tastyware/coredis-utils"
+Changelog = "https://github.com/tastyware/coredis-utils/releases"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.406",
+    "pytest>=8.4.2",
+    "ruff>=0.13.1",
+    "trio>=0.30.0",
+    "uvloop>=0.22.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = "tests"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pyright]
+strict = ["coredis_utils/"]