Yet another Python cache library

.gitignore

@@ -0,0 +1 @@
+*.py[co]

LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present Erle Carrara <[email protected]>
+
+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.

README.md

@@ -0,0 +1,103 @@
+# yapcache
+
+[![PyPI - Version](https://img.shields.io/pypi/v/yapcache.svg)](https://pypi.org/project/yapcache)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/yapcache.svg)](https://pypi.org/project/yapcache)
+
+Yet another Python cache library.
+
+**Table of Contents**
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [License](#license)
+
+## Installation
+
+```console
+pip install yapcache
+```
+
+## Usage
+
+In memory cache:
+
+```python
+import asyncio
+from yapcache import memoize
+from yapcache.caches.memory import InMemoryCache
+
+cache = InMemoryCache(maxsize=1_000, key_prefix=f"example:")
+
+
+@memoize(cache, ttl=60, cache_key=lambda n: f"slow-{n}")
+async def slow_fn(n: int):
+    await asyncio.sleep(n)
+
+
+async def example():
+    await slow_fn(3)
+    await slow_fn(3)  # cached!
+
+
+asyncio.run(example())
+```
+
+Redis cache:
+
+```python
+# ...
+from redis.asyncio.client import Redis
+from yapcache.caches.redis import RedisCache
+
+
+redis_client = Redis()
+cache = RedisCache(redis_client, key_prefix=f"example:")
+```
+
+Multi-layer cache:
+
+```python
+# ...
+from yapcache.caches import MultiLayerCache
+
+redis_client = Redis()
+
+cache = MultiLayerCache(
+    [InMemoryCache(maxsize=2_000), RedisCache(redis_client)],
+    key_prefix=f"example:",
+)
+```
+
+Use `lock` parameter to protect against thundering herd (only one coroutine/thread
+will do the work and update the cache):
+
+```python
+# ...
+from yapcache.distlock import RedisDistLock
+
+@memoize(
+    cache,
+    ttl=60,
+    cache_key=lambda n: f"slow-{n}",
+    lock=lambda key: RedisDistLock(redis_client, key),
+)
+async def slow_fn(n: int):
+    # ...
+```
+
+Use `best_before` to serve stale data (update the cache in background):
+
+```python
+@memoize(
+    cache,
+    ttl=60,
+    cache_key=lambda n: f"slow-{n}",
+    best_before=lambda n: time.time() + 30
+)
+async def slow_fn(n: int):
+    # ...
+```
+
+## License
+
+`yapcache` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yapcache"
+dynamic = ["version"]
+description = ''
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+keywords = []
+authors = [{ name = "Erle Carrara", email = "[email protected]" }]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Framework :: AsyncIO",
+]
+dependencies = ["redis>=5.0,<6", "cachebox>=4.1,<5"]
+
+[project.urls]
+Documentation = "https://github.com/ecarrara/yapcache#readme"
+Issues = "https://github.com/ecarrara/yapcache/issues"
+Source = "https://github.com/ecarrara/yapcache"
+
+[tool.hatch.version]
+path = "src/yapcache/__about__.py"
+
+[tool.hatch.envs.default]
+dependencies = ["coverage[toml]>=6.5", "pytest", "ruff"]
+
+[tool.hatch.envs.default.scripts]
+test = "pytest {args:tests}"
+test-cov = "coverage run -m pytest {args:tests}"
+cov-report = ["- coverage combine", "coverage report"]
+cov = ["test-cov", "cov-report"]
+
+[[tool.hatch.envs.all.matrix]]
+python = ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+[tool.hatch.envs.types]
+dependencies = ["mypy>=1.0.0"]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/yapcache tests}"
+
+[tool.coverage.run]
+source_pkgs = ["yapcache", "tests"]
+branch = true
+parallel = true
+omit = ["src/yapcache/__about__.py"]
+
+[tool.coverage.paths]
+yapcache = ["src/yapcache", "*/yapcache/src/yapcache"]
+tests = ["tests", "*/yapcache/tests"]
+
+[tool.coverage.report]
+exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]

pyrightconfig.json

@@ -0,0 +1,7 @@
+{
+  "extraPaths": [
+    "./src",
+    "/Users/ecarrara/Library/Application Support/hatch/env/virtual/yapcache/YUOa77rk/yapcache//lib/python3.12/site-packages"
+  ],
+  "pythonVersion": "3.12"
+}

src/yapcache/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

src/yapcache/__init__.py

@@ -0,0 +1,75 @@
+import asyncio
+import functools
+import pickle
+import time
+from dataclasses import dataclass, replace
+from functools import wraps
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Coroutine,
+    Optional,
+    ParamSpec,
+    TypeVar,
+    cast,
+    override,
+)
+
+import cachebox
+from redis.asyncio import Redis
+
+from yapcache.cache_item import CacheItem
+from yapcache.caches import Cache
+from yapcache.distlock import DistLock, NullLock
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def memoize(
+    cache: Cache,
+    cache_key: Callable[P, str],
+    ttl: float,
+    best_before: Callable[[R], Optional[float]] = lambda *a, **kw: None,
+    lock: Callable[[str], DistLock] = lambda *a, **kw: NullLock(),
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
+    update_tasks: dict[str, asyncio.Task] = {}
+
+    def decorator(fn: Callable[P, Awaitable[R]]):
+        @wraps(fn)
+        async def wrapper(*args, **kwargs):
+            key = cache_key(*args, **kwargs)
+
+            async def _call_with_lock():
+                async with lock(key + ":lock"):
+                    found = await cache.get(key)
+                    if isinstance(found, CacheItem):
+                        return found.value
+
+                    result = await fn(*args, **kwargs)
+
+                    await cache.set(
+                        key,
+                        value=result,
+                        ttl=ttl,
+                        best_before=best_before(result),
+                    )
+
+                    return result
+
+            found = await cache.get(key)
+            if isinstance(found, CacheItem):
+                if found.is_stale and key not in update_tasks:
+                    task = asyncio.create_task(_call_with_lock())
+                    update_tasks[key] = task  # TODO: acho que tem problema
+                    task.add_done_callback(lambda _: update_tasks.pop(key))
+                return found.value
+
+            result = await _call_with_lock()
+
+            return result
+
+        return wrapper
+
+    return decorator

src/yapcache/cache_item.py

@@ -0,0 +1,29 @@
+import time
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True, eq=True)
+class CacheItem:
+    """A value retrievied from cache."""
+
+    value: Any
+    """The cached value."""
+
+    ttl: float | None = None
+    """Time-to-live in seconds."""
+
+    best_before: float | None = None
+    """Best before this timestamp."""
+
+    @property
+    def is_stale(self):
+        if self.best_before is None:
+            return False
+        return time.time() > self.best_before
+
+
+class NotFound: ...
+
+
+NOT_FOUND = NotFound()

src/yapcache/caches/__init__.py

@@ -0,0 +1,70 @@
+import asyncio
+from typing import Any, override
+
+from yapcache.cache_item import NOT_FOUND, CacheItem, NotFound
+
+
+class Cache:
+    def __init__(self, key_prefix: str = ""):
+        self.key_prefix = key_prefix
+
+    def _key(self, key):
+        return f"{self.key_prefix}{key}"
+
+    async def get(self, key: str) -> CacheItem | NotFound:
+        raise NotImplementedError
+
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None,
+        best_before: float | None = None,
+    ):
+        raise NotImplementedError
+
+    async def close(self): ...
+
+
+class MultiLayerCache(Cache):
+    def __init__(self, caches: list[Cache] = [], **kwargs):
+        super().__init__(**kwargs)
+        self.caches = caches
+
+    @override
+    async def close(self):
+        await asyncio.gather(*(cache.close() for cache in self.caches))
+
+    @override
+    async def get(self, key: str) -> CacheItem | NotFound:
+        key = self._key(key)
+        found = NOT_FOUND
+
+        index = 0
+        for cache in self.caches:
+            found = await cache.get(key)
+            if found != NOT_FOUND:
+                break
+            index += 1
+
+        if not isinstance(found, NotFound):
+            await asyncio.gather(
+                *(
+                    cache.set(key, found.value, found.ttl)
+                    for cache in self.caches[:index]
+                )
+            )
+        return found
+
+    @override
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None,
+        best_before: float | None = None,
+    ):
+        key = self._key(key)
+        await asyncio.gather(
+            *(cache.set(key, value, ttl, best_before) for cache in self.caches),
+        )

src/yapcache/caches/memory.py

@@ -0,0 +1,34 @@
+from dataclasses import replace
+from typing import Any, override
+
+import cachebox
+
+from yapcache.cache_item import NOT_FOUND, CacheItem, NotFound
+from yapcache.caches import Cache
+
+
+class InMemoryCache(Cache):
+    def __init__(self, maxsize: int, capacity: int = 0, **kwargs):
+        super().__init__(**kwargs)
+        self._cache = cachebox.VTTLCache(maxsize=maxsize, capacity=capacity)
+
+    @override
+    async def get(self, key: str) -> CacheItem | NotFound:
+        value, ttl = self._cache.get_with_expire(self._key(key), default=NOT_FOUND)
+        if isinstance(value, NotFound):
+            return value
+        return replace(value, ttl=ttl)
+
+    @override
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        ttl: float | None,
+        best_before: float | None = None,
+    ):
+        return self._cache.insert(
+            key=self._key(key),
+            value=CacheItem(value=value, best_before=best_before, ttl=ttl),
+            ttl=ttl,
+        )