recall-cache 0.1.0__tar.gz

recall_cache-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.venv
+venv/
+ENV/
+env/
+.cache/
+*.cache
+.github/

recall_cache-0.1.0/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.

recall_cache-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/README_FA.md

@@ -0,0 +1,117 @@
+# ریکال — کش هوشمند برای هر تابعی
+
+کش هوشمند برای هر تابعی — ساده مثل requests.
+
+```python
+from recall import cache
+
+@cache(ttl="1h")
+def get_user(user_id):
+    return db.query(user_id)
+```
+
+## ویژگی‌ها
+
+- **API ساده** — فقط با `@cache(ttl="1h")` هر تابعی رو کش کن
+- **چندین بک‌اند** — حافظه، دیسک، ردیس
+- **انقدا ساده** — `"30m"`، `"1h"`، `"7d"` به جای ثانیه
+- **حذف LRU** — تمیز کردن خودکار وقتی به حداکثر رسیدی
+- **ایمن برای ترد** — در محیط‌های همزمان کار می‌کنه
+- **بدون وابستگی** — بک‌اند ردیس اختیاریه
+
+## نصب
+
+```bash
+pip install recall
+# با پشتیبانی ردیس:
+pip install recall[redis]
+```
+
+## شروع سریع
+
+```python
+from recall import cache
+import time
+
+@cache(ttl="1h", maxsize=1000)
+def expensive_func(x):
+    time.sleep(2)
+    return x * 2
+
+# اولین فراخوانی: محاسبه می‌کنه
+result = expensive_func(5)  # ۲ ثانیه طول می‌کشه
+
+# دومین فراخوانی: فوری (از کش)
+result = expensive_func(5)  # فوری برمی‌گردونه
+```
+
+## بک‌اند‌ها
+
+### حافظه (پیش‌فرض)
+
+```python
+@cache(ttl="1h", maxsize=1000)
+def func(x):
+    return x * 2
+```
+
+### دیسک (دائمی)
+
+```python
+from recall import DiskBackend
+
+@cache(ttl="1h", backend=DiskBackend("/tmp/my_cache"))
+def func(x):
+    return x * 2
+```
+
+### ردیس
+
+```python
+from recall import RedisBackend
+
+@cache(ttl="1h", backend=RedisBackend("redis://localhost:6379"))
+def func(x):
+    return x * 2
+```
+
+## مدیریت کش
+
+```python
+# پاک کردن همه مقادیر کش شده
+expensive_func.cache_clear()
+
+# حذف یک کلید خاص
+expensive_func.cache_delete(42)
+
+# تابع کلید سفارشی
+@cache(ttl="1h", key_fn=lambda f, a, k: f"{a}_{k.get('mode', '')}")
+def custom(data, mode):
+    return f"{data}_{mode}"
+```
+
+## فرمت‌های انقضا
+
+| مختصر | معنی |
+|--------|------|
+| `"30s"` | ۳۰ ثانیه |
+| `"5m"` | ۵ دقیقه |
+| `"1h"` | ۱ ساعت |
+| `"1d"` | ۱ روز |
+| `"1w"` | ۱ هفته |
+| `3600` | ثانیه خام (int/float) |
+
+## چرا ریکال؟
+
+| ابزار | مشکل |
+|--------|------|
+| `functools.lru_cache` | بدون انقضا، بدون دائمی بودن |
+| `cachetools` | API پیچیده، بدون دیسک/ردیس |
+| `redis` به تنهایی | مدیریت دستی کلید |
+| `dogpile.cache` | بیش از حد ساده برای استفاده ساده |
+
+**ریکال** = API ساده + بک‌اند واقعی + انقضا درست انجام شده.
+
+## مجوز
+
+MIT

recall_cache-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "recall-cache"
+version = "0.1.0"
+description = "Smart caching for any function — simple as requests"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [
+    { name = "hermes-telegram", email = "hermes_tm@agentmail.to" },
+]
+keywords = ["cache", "caching", "ttl", "memoize", "redis", "diskcache"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=4.0"]
+dev = ["pytest", "redis"]
+
+[project.urls]
+Homepage = "https://github.com/hermes-telegram/recall"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/recall"]

recall_cache-0.1.0/src/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-0.1.0/src/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/tests/test_recall.py

@@ -0,0 +1,452 @@
+"""Comprehensive tests for recall."""
+
+import os
+import shutil
+import time
+import pytest
+from recall import cache, MemoryBackend, DiskBackend
+
+
+# ============================================================
+# Memory Backend Tests
+# ============================================================
+
+class TestMemoryBackend:
+    def test_set_and_get(self):
+        be = MemoryBackend()
+        be.set("key1", "value1", ttl=60)
+        result = be.get("key1")
+        assert result is not None
+        _, value = result
+        assert value == "value1"
+
+    def test_get_missing(self):
+        be = MemoryBackend()
+        assert be.get("nonexistent") is None
+
+    def test_expiration(self):
+        be = MemoryBackend()
+        be.set("key1", "value1", ttl=0.1)
+        time.sleep(0.15)
+        assert be.get("key1") is None
+
+    def test_delete(self):
+        be = MemoryBackend()
+        be.set("key1", "value1", ttl=60)
+        be.delete("key1")
+        assert be.get("key1") is None
+
+    def test_clear(self):
+        be = MemoryBackend()
+        be.set("k1", "v1", ttl=60)
+        be.set("k2", "v2", ttl=60)
+        be.clear()
+        assert be.get("k1") is None
+        assert be.get("k2") is None
+
+    def test_maxsize_eviction(self):
+        be = MemoryBackend(maxsize=3)
+        for i in range(5):
+            be.set(f"k{i}", f"v{i}", ttl=60)
+        # Only 3 should remain
+        count = sum(1 for i in range(5) if be.get(f"k{i}") is not None)
+        assert count == 3
+
+    def test_lru_eviction(self):
+        be = MemoryBackend(maxsize=3)
+        be.set("a", 1, ttl=60)
+        be.set("b", 2, ttl=60)
+        be.set("c", 3, ttl=60)
+        # Access "a" to make it recently used
+        be.get("a")
+        # Add "d" — should evict "b" (least recently used)
+        be.set("d", 4, ttl=60)
+        assert be.get("a") is not None
+        assert be.get("b") is None
+        assert be.get("c") is not None
+        assert be.get("d") is not None
+
+    def test_overwrite(self):
+        be = MemoryBackend()
+        be.set("key1", "old", ttl=60)
+        be.set("key1", "new", ttl=60)
+        _, value = be.get("key1")
+        assert value == "new"
+
+    def test_various_types(self):
+        be = MemoryBackend()
+        be.set("int", 42, ttl=60)
+        be.set("list", [1, 2, 3], ttl=60)
+        be.set("dict", {"a": 1}, ttl=60)
+        be.set("none", None, ttl=60)
+        be.set("tuple", (1, 2), ttl=60)
+        assert be.get("int")[1] == 42
+        assert be.get("list")[1] == [1, 2, 3]
+        assert be.get("dict")[1] == {"a": 1}
+        assert be.get("none")[1] is None
+        assert be.get("tuple")[1] == (1, 2)
+
+
+# ============================================================
+# Disk Backend Tests
+# ============================================================
+
+class TestDiskBackend:
+    def setup_method(self):
+        self.dir = ".test_recall_cache"
+
+    def teardown_method(self):
+        if os.path.exists(self.dir):
+            shutil.rmtree(self.dir)
+
+    def test_set_and_get(self):
+        be = DiskBackend(self.dir)
+        be.set("key1", "value1", ttl=60)
+        result = be.get("key1")
+        assert result is not None
+        assert result[1] == "value1"
+
+    def test_get_missing(self):
+        be = DiskBackend(self.dir)
+        assert be.get("nonexistent") is None
+
+    def test_expiration(self):
+        be = DiskBackend(self.dir)
+        be.set("key1", "value1", ttl=0.1)
+        time.sleep(0.15)
+        assert be.get("key1") is None
+
+    def test_delete(self):
+        be = DiskBackend(self.dir)
+        be.set("key1", "value1", ttl=60)
+        be.delete("key1")
+        assert be.get("key1") is None
+
+    def test_clear(self):
+        be = DiskBackend(self.dir)
+        be.set("k1", "v1", ttl=60)
+        be.set("k2", "v2", ttl=60)
+        be.clear()
+        assert be.get("k1") is None
+        assert be.get("k2") is None
+
+    def test_persistence(self):
+        be = DiskBackend(self.dir)
+        be.set("key1", {"complex": "data"}, ttl=60)
+        # Create new backend instance (simulates restart)
+        be2 = DiskBackend(self.dir)
+        result = be2.get("key1")
+        assert result is not None
+        assert result[1] == {"complex": "data"}
+
+    def test_various_types(self):
+        be = DiskBackend(self.dir)
+        be.set("int", 42, ttl=60)
+        be.set("list", [1, 2, 3], ttl=60)
+        be.set("dict", {"a": 1}, ttl=60)
+        be.set("none", None, ttl=60)
+        assert be.get("int")[1] == 42
+        assert be.get("list")[1] == [1, 2, 3]
+        assert be.get("dict")[1] == {"a": 1}
+        assert be.get("none")[1] is None
+
+
+# ============================================================
+# Decorator Tests
+# ============================================================
+
+class TestCacheDecorator:
+    def test_basic_caching(self):
+        call_count = 0
+
+        @cache(ttl="1h")
+        def add(a, b):
+            nonlocal call_count
+            call_count += 1
+            return a + b
+
+        assert add(2, 3) == 5
+        assert add(2, 3) == 5  # Should use cache
+        assert call_count == 1
+
+    def test_different_args(self):
+        call_count = 0
+
+        @cache(ttl="1h")
+        def add(a, b):
+            nonlocal call_count
+            call_count += 1
+            return a + b
+
+        assert add(2, 3) == 5
+        assert add(3, 4) == 7
+        assert call_count == 2
+
+    def test_ttl_expiration(self):
+        call_count = 0
+
+        @cache(ttl=0.1)
+        def add(a, b):
+            nonlocal call_count
+            call_count += 1
+            return a + b
+
+        assert add(2, 3) == 5
+        time.sleep(0.15)
+        assert add(2, 3) == 5  # Recomputed
+        assert call_count == 2
+
+    def test_cache_clear(self):
+        call_count = 0
+
+        @cache(ttl="1h")
+        def add(a, b):
+            nonlocal call_count
+            call_count += 1
+            return a + b
+
+        add(2, 3)
+        add.cache_clear()
+        add(2, 3)
+        assert call_count == 2
+
+    def test_cache_delete(self):
+        call_count = 0
+
+        @cache(ttl="1h")
+        def add(a, b):
+            nonlocal call_count
+            call_count += 1
+            return a + b
+
+        add(2, 3)
+        add.cache_delete(2, 3)
+        add(2, 3)
+        assert call_count == 2
+
+    def test_kwargs_caching(self):
+        call_count = 0
+
+        @cache(ttl="1h")
+        def greet(name, greeting="Hello"):
+            nonlocal call_count
+            call_count += 1
+            return f"{greeting}, {name}!"
+
+        assert greet("Alice") == "Hello, Alice!"
+        assert greet("Alice") == "Hello, Alice!"
+        assert greet("Alice", greeting="Hi") == "Hi, Alice!"
+        assert call_count == 2
+
+    def test_custom_key_fn(self):
+        call_count = 0
+
+        @cache(ttl="1h", key_fn=lambda f, a, k: f"{a[0]}_{k.get('mode', '')}")
+        def process(data, mode):
+            nonlocal call_count
+            call_count += 1
+            return f"{data}_{mode}"
+
+        assert process("x", mode="y") == "x_y"
+        assert process("x", mode="z") == "x_z"  # Different key
+        assert call_count == 2
+
+    def test_custom_backend(self):
+        be = MemoryBackend()
+        call_count = 0
+
+        @cache(ttl="1h", backend=be)
+        def add(a, b):
+            nonlocal call_count
+            call_count += 1
+            return a + b
+
+        add(2, 3)
+        # Verify backend has the key
+        assert len(be._cache) == 1
+
+    def test_functools_wraps(self):
+        @cache(ttl="1h")
+        def my_func(a, b):
+            """My docstring."""
+            return a + b
+
+        assert my_func.__name__ == "my_func"
+        assert my_func.__doc__ == "My docstring."
+
+    def test_exception_not_cached(self):
+        call_count = 0
+
+        @cache(ttl="1h")
+        def fail():
+            nonlocal call_count
+            call_count += 1
+            raise ValueError("oops")
+
+        with pytest.raises(ValueError):
+            fail()
+        with pytest.raises(ValueError):
+            fail()
+        assert call_count == 2  # Not cached
+
+    def test_none_return(self):
+        call_count = 0
+
+        @cache(ttl="1h")
+        def return_none():
+            nonlocal call_count
+            call_count += 1
+            return None
+
+        assert return_none() is None
+        assert return_none() is None
+        assert call_count == 1  # Cached
+
+    def test_ttl_parsing(self):
+        # Test various TTL formats
+        call_count = 0
+
+        @cache(ttl="1s")
+        def f1():
+            nonlocal call_count
+            call_count += 1
+            return 1
+
+        @cache(ttl="5m")
+        def f2():
+            nonlocal call_count
+            call_count += 1
+            return 2
+
+        @cache(ttl="2h")
+        def f3():
+            nonlocal call_count
+            call_count += 1
+            return 3
+
+        @cache(ttl="1d")
+        def f4():
+            nonlocal call_count
+            call_count += 1
+            return 4
+
+        @cache(ttl="1w")
+        def f5():
+            nonlocal call_count
+            call_count += 1
+            return 5
+
+        @cache(ttl=3600)  # raw seconds
+        def f6():
+            nonlocal call_count
+            call_count += 1
+            return 6
+
+        f1(); f2(); f3(); f4(); f5(); f6()
+        assert call_count == 6
+
+    def test_nested_decorator(self):
+        @cache(ttl="1h")
+        @staticmethod
+        def add(a, b):
+            return a + b
+
+        assert add(2, 3) == 5
+
+    def test_method_caching(self):
+        class Calculator:
+            def __init__(self):
+                self.calls = 0
+
+            @cache(ttl="1h")
+            def add(self, a, b):
+                self.calls += 1
+                return a + b
+
+        calc = Calculator()
+        assert calc.add(2, 3) == 5
+        assert calc.add(2, 3) == 5
+        assert calc.calls == 1
+
+    def test_concurrent_access(self):
+        import threading
+
+        @cache(ttl="1h")
+        def slow_func(x):
+            time.sleep(0.01)
+            return x * 2
+
+        results = []
+        def worker():
+            results.append(slow_func(5))
+
+        threads = [threading.Thread(target=worker) for _ in range(10)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert all(r == 10 for r in results)
+
+
+# ============================================================
+# Integration Tests
+# ============================================================
+
+class TestIntegration:
+    def test_memory_to_disk(self):
+        """Test that data can be cached in memory and retrieved from disk."""
+        mem_be = MemoryBackend()
+        disk_be = DiskBackend(".test_integration_cache")
+
+        try:
+            @cache(ttl="1h", backend=mem_be)
+            def compute(x):
+                return x * 2
+
+            result = compute(5)
+            assert result == 10
+
+            # Verify it's in memory
+            assert mem_be.get("some_key") is None  # Different key
+        finally:
+            shutil.rmtree(".test_integration_cache", ignore_errors=True)
+
+    def test_real_world_pattern(self):
+        """Simulate real-world usage: API call caching."""
+        api_calls = []
+
+        @cache(ttl="5m")
+        def fetch_user(user_id):
+            api_calls.append(user_id)
+            return {"id": user_id, "name": f"User {user_id}"}
+
+        # First call hits the API
+        user = fetch_user(1)
+        assert user["name"] == "User 1"
+        assert len(api_calls) == 1
+
+        # Second call uses cache
+        user = fetch_user(1)
+        assert user["name"] == "User 1"
+        assert len(api_calls) == 1
+
+        # Different user hits the API
+        user = fetch_user(2)
+        assert user["name"] == "User 2"
+        assert len(api_calls) == 2
+
+    def test_cache_invalidation_pattern(self):
+        """Test manual cache invalidation."""
+        @cache(ttl="1h")
+        def get_config(key):
+            return f"value_for_{key}"
+
+        get_config("db_host")
+        get_config("db_port")
+
+        # Invalidate one
+        get_config.cache_delete("db_host")
+
+        # db_host should be gone, db_port should remain
+        # (we can't easily check this without accessing backend directly)