recall-cache 0.1.0__py3-none-any.whl

recall/__init__.py

@@ -0,0 +1,6 @@
+"""recall — smart caching for any function, simple as requests."""
+
+from .cache import cache, CacheBackend, MemoryBackend, DiskBackend, RedisBackend
+
+__all__ = ["cache", "CacheBackend", "MemoryBackend", "DiskBackend", "RedisBackend"]
+__version__ = "0.1.0"

recall/cache.py

@@ -0,0 +1,217 @@
+"""Core cache decorator and backends for recall."""
+
+import functools
+import hashlib
+import json
+import os
+import pickle
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Optional, Union
+
+
+class CacheBackend(ABC):
+    """Abstract base class for cache backends."""
+
+    @abstractmethod
+    def get(self, key: str) -> Optional[tuple[float, Any]]:
+        """Return (expire_time, value) or None."""
+        ...
+
+    @abstractmethod
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        """Store value with TTL in seconds."""
+        ...
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete a key."""
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Clear all cached values."""
+        ...
+
+
+class MemoryBackend(CacheBackend):
+    """In-memory cache with TTL and maxsize (LRU eviction)."""
+
+    def __init__(self, maxsize: int = 1000):
+        self._cache: dict[str, tuple[float, Any]] = {}
+        self._access: dict[str, float] = {}
+        self.maxsize = maxsize
+
+    def get(self, key: str) -> Optional[tuple[float, Any]]:
+        if key in self._cache:
+            expire_time, value = self._cache[key]
+            if expire_time > time.time():
+                self._access[key] = time.time()
+                return (expire_time, value)
+            else:
+                del self._cache[key]
+                del self._access[key]
+        return None
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        if len(self._cache) >= self.maxsize and key not in self._cache:
+            self._evict()
+        self._cache[key] = (time.time() + ttl, value)
+        self._access[key] = time.time()
+
+    def delete(self, key: str) -> None:
+        self._cache.pop(key, None)
+        self._access.pop(key, None)
+
+    def clear(self) -> None:
+        self._cache.clear()
+        self._access.clear()
+
+    def _evict(self):
+        """Evict least recently used item."""
+        if self._access:
+            oldest = min(self._access, key=self._access.get)
+            del self._cache[oldest]
+            del self._access[oldest]
+
+
+class DiskBackend(CacheBackend):
+    """Persistent disk cache using pickle files."""
+
+    def __init__(self, directory: str = ".recall_cache"):
+        self.directory = directory
+        os.makedirs(directory, exist_ok=True)
+
+    def _path(self, key: str) -> str:
+        safe = hashlib.sha256(key.encode()).hexdigest()[:16]
+        return os.path.join(self.directory, f"{safe}.cache")
+
+    def get(self, key: str) -> Optional[tuple[float, Any]]:
+        path = self._path(key)
+        if os.path.exists(path):
+            try:
+                with open(path, "rb") as f:
+                    expire_time, value = pickle.load(f)
+                if expire_time > time.time():
+                    return (expire_time, value)
+                else:
+                    os.remove(path)
+            except (pickle.PickleError, OSError):
+                pass
+        return None
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        path = self._path(key)
+        with open(path, "wb") as f:
+            pickle.dump((time.time() + ttl, value), f)
+
+    def delete(self, key: str) -> None:
+        path = self._path(key)
+        if os.path.exists(path):
+            os.remove(path)
+
+    def clear(self) -> None:
+        for f in os.listdir(self.directory):
+            if f.endswith(".cache"):
+                os.remove(os.path.join(self.directory, f))
+
+
+class RedisBackend(CacheBackend):
+    """Redis cache backend."""
+
+    def __init__(self, url: str = "redis://localhost:6379", prefix: str = "recall:"):
+        import redis
+        self.client = redis.from_url(url)
+        self.prefix = prefix
+
+    def _key(self, key: str) -> str:
+        return f"{self.prefix}{key}"
+
+    def get(self, key: str) -> Optional[tuple[float, Any]]:
+        raw = self.client.get(self._key(key))
+        if raw:
+            return pickle.loads(raw)
+        return None
+
+    def set(self, key: str, value: Any, ttl: float) -> None:
+        data = pickle.dumps((time.time() + ttl, value))
+        self.client.setex(self._key(key), int(ttl), data)
+
+    def delete(self, key: str) -> None:
+        self.client.delete(self._key(key))
+
+    def clear(self) -> None:
+        keys = self.client.keys(f"{self.prefix}*")
+        if keys:
+            self.client.delete(*keys)
+
+
+def _make_key(func: Callable, args: tuple, kwargs: dict) -> str:
+    """Generate a unique cache key from function and arguments."""
+    key_data = json.dumps({
+        "func": f"{func.__module__}.{func.__qualname__}",
+        "args": args,
+        "kwargs": kwargs,
+    }, sort_keys=True, default=str)
+    return hashlib.sha256(key_data.encode()).hexdigest()
+
+
+def cache(
+    ttl: Union[str, float] = "1h",
+    maxsize: int = 1000,
+    backend: Optional[CacheBackend] = None,
+    key_fn: Optional[Callable] = None,
+):
+    """
+    Decorator that caches function results with TTL.
+
+    Args:
+        ttl: Time-to-live in seconds, or shorthand like "1h", "30m", "7d".
+        maxsize: Maximum number of cached items (memory backend only).
+        backend: Custom backend (MemoryBackend, DiskBackend, RedisBackend).
+        key_fn: Custom key function f(func, args, kwargs) -> str.
+
+    Usage:
+        @cache(ttl="1h")
+        def get_user(user_id):
+            return db.query(user_id)
+
+        @cache(ttl=300, backend=DiskBackend("/tmp/cache"))
+        def expensive_computation(x, y):
+            return x ** y
+    """
+    # Parse TTL shorthand
+    if isinstance(ttl, str):
+        multipliers = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}
+        ttl = float(ttl[:-1]) * multipliers.get(ttl[-1].lower(), 1)
+
+    if backend is None:
+        backend = MemoryBackend(maxsize=maxsize)
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if key_fn:
+                k = key_fn(func, args, kwargs)
+            else:
+                k = _make_key(func, args, kwargs)
+
+            result = backend.get(k)
+            if result is not None:
+                _, value = result
+                return value
+
+            value = func(*args, **kwargs)
+            backend.set(k, value, ttl)
+            return value
+
+        # Attach cache management methods
+        wrapper.cache_backend = backend
+        wrapper.cache_clear = backend.clear
+        wrapper.cache_delete = lambda *a, **kw: backend.delete(
+            key_fn(func, a, kw) if key_fn else _make_key(func, a, kw)
+        )
+
+        return wrapper
+
+    return decorator

recall_cache-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: recall-cache
+Version: 0.1.0
+Summary: Smart caching for any function — simple as requests
+Project-URL: Homepage, https://github.com/hermes-telegram/recall
+Author-email: hermes-telegram <hermes_tm@agentmail.to>
+License: MIT
+License-File: LICENSE
+Keywords: cache,caching,diskcache,memoize,redis,ttl
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: redis; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# recall
+
+Smart caching for any function — simple as requests.
+
+```python
+from recall import cache
+
+@cache(ttl="1h")
+def get_user(user_id):
+    return db.query(user_id)
+```
+
+## Features
+
+- **Simple API** — just `@cache(ttl="1h")` on any function
+- **Multiple backends** — Memory, Disk, Redis
+- **TTL shorthand** — `"30m"`, `"1h"`, `"7d"` instead of raw seconds
+- **LRU eviction** — automatic cleanup when maxsize is reached
+- **Thread-safe** — works in concurrent environments
+- **Zero dependencies** — Redis backend optional
+
+## Install
+
+```bash
+pip install recall
+# With Redis support:
+pip install recall[redis]
+```
+
+## Quick Start
+
+```python
+from recall import cache
+import time
+
+@cache(ttl="1h", maxsize=1000)
+def expensive_func(x):
+    time.sleep(2)
+    return x * 2
+
+# First call: computes
+result = expensive_func(5)  # takes 2 seconds
+
+# Second call: instant (from cache)
+result = expensive_func(5)  # returns immediately
+```
+
+## Backends
+
+### Memory (default)
+
+```python
+@cache(ttl="1h", maxsize=1000)
+def func(x):
+    return x * 2
+```
+
+### Disk (persistent)
+
+```python
+from recall import DiskBackend
+
+@cache(ttl="1h", backend=DiskBackend("/tmp/my_cache"))
+def func(x):
+    return x * 2
+```
+
+### Redis
+
+```python
+from recall import RedisBackend
+
+@cache(ttl="1h", backend=RedisBackend("redis://localhost:6379"))
+def func(x):
+    return x * 2
+```
+
+## Cache Management
+
+```python
+# Clear all cached values
+expensive_func.cache_clear()
+
+# Delete specific key
+expensive_func.cache_delete(42)
+
+# Custom key function
+@cache(ttl="1h", key_fn=lambda f, a, k: f"{a}_{k.get('mode', '')}")
+def custom(data, mode):
+    return f"{data}_{mode}"
+```
+
+## TTL Formats
+
+| Shorthand | Meaning |
+|-----------|---------|
+| `"30s"` | 30 seconds |
+| `"5m"` | 5 minutes |
+| `"1h"` | 1 hour |
+| `"1d"` | 1 day |
+| `"1w"` | 1 week |
+| `3600` | raw seconds (int/float) |
+
+## Why recall?
+
+| Tool | Issue |
+|------|-------|
+| `functools.lru_cache` | No TTL, no persistence |
+| `cachetools` | Complex API, no disk/Redis |
+| `redis` alone | Manual key management |
+| `dogpile.cache` | Overkill for simple use |
+
+**recall** = simple API + real backends + TTL done right.
+
+## License
+
+MIT

recall_cache-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+recall/__init__.py,sha256=DQYA2z6XR4n_xu7Em5ROigsS6q-QOLIxC325RHKuOfw,258
+recall/cache.py,sha256=eEsOGGgplO-6wKp3qTgRVqKelZ2uRYrb0Gg-kTcWulw,6594
+recall_cache-0.1.0.dist-info/METADATA,sha256=-XgG4R50aqdcjk0cehYwrRPjCe-xINWUZxwu4hHEFDI,2882
+recall_cache-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+recall_cache-0.1.0.dist-info/licenses/LICENSE,sha256=JlZ8sQSp-7ydoSasBSWtgwHJ1QmauZOM8wxQ1gfgrXA,1072
+recall_cache-0.1.0.dist-info/RECORD,,

recall_cache-0.1.0.dist-info/WHEEL

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

recall_cache-0.1.0.dist-info/licenses/LICENSE

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