purecache 0.1.0__tar.gz

purecache-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: purecache
+Version: 0.1.0
+Summary: Async-native in-memory cache with pluggable eviction backends. Pure Python, zero dependencies.
+Author-email: Maksim Smirnoff <smirnoffmg@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pure-python-system-design/purecache
+Project-URL: Documentation, https://pure-python-system-design.github.io/purecache/
+Project-URL: Repository, https://github.com/pure-python-system-design/purecache
+Project-URL: Bug Tracker, https://github.com/pure-python-system-design/purecache/issues
+Project-URL: Changelog, https://github.com/pure-python-system-design/purecache/releases
+Keywords: cache,lru,lfu,ttl,asyncio,async,in-memory,system-design
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# 🗄️ purecache
+
+Async-native in-memory cache with pluggable eviction backends — pure Python 3.12+, zero dependencies.
+
+Just `asyncio`, `collections.OrderedDict`, and the irrational urge to understand what happens inside the black box.
+
+Part of the [pure-python-system-design](https://github.com/pure-python-system-design) project.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install purecache
+```
+
+Or with uv:
+
+```bash
+uv add purecache
+```
+
+Python 3.12+ required.
+
+---
+
+## ⚡ Quick Start
+
+### Direct backend usage
+
+```python
+from purecache.backends.lru import LRUCache
+
+cache = LRUCache(capacity=128)
+
+await cache.put("user:42", {"name": "Alice"})
+value = await cache.get("user:42")  # {"name": "Alice"}
+value = await cache.get("missing")  # None
+```
+
+### Decorator
+
+```python
+from purecache.decorators import cache
+from purecache.backends.lru import LRUCache
+
+@cache(backend=LRUCache, capacity=128)
+async def get_user(user_id: str) -> dict:
+    return await fetch_from_db(user_id)
+
+# First call — executes get_user, caches result
+user = await get_user("42")
+
+# Second call — returns cached result, skips get_user
+user = await get_user("42")
+```
+
+Cache keys are derived automatically from the function's arguments using `pickle` + SHA-256 — positional args keep their order, keyword args are sorted by name.
+
+---
+
+## 🧠 Backends
+
+| Backend       | Eviction Policy       | Time | Memory | Best For               |
+| ------------- | --------------------- | ---- | ------ | ---------------------- |
+| `LRUCache`    | Least Recently Used   | O(1) | O(n)   | General purpose        |
+| `LFUCache`    | Least Frequently Used | O(1) | O(n)   | Skewed access patterns |
+| `TTLCache`    | Time-based expiry     | O(1) | O(n)   | Sessions, tokens       |
+| `LRUTTLCache` | LRU + TTL combined    | O(1) | O(n)   | Production default     |
+
+All backends implement the `ICacheBackend` protocol — swap them without touching your application code.
+
+---
+
+## 🔌 Framework Examples
+
+The decorator integrates naturally with any async framework:
+
+```python
+# FastAPI
+from fastapi import FastAPI
+from purecache.decorators import cache
+from purecache.backends.lru import LRUCache
+
+app = FastAPI()
+
+@app.get("/user/{user_id}")
+@cache(backend=LRUCache, capacity=512)
+async def get_user(user_id: str):
+    return await fetch_user_from_db(user_id)
+```
+
+TODO: Add more examples for aiohttp, Django, Flask, Litestar, and Sanic in [`examples/`](examples/).
+
+---
+
+## 📐 Architecture
+
+```
+cache() decorator
+  └── ICacheBackend (protocol)
+        ├── LRUCache    — OrderedDict + move_to_end
+        ├── LFUCache    — key_map + freq_map + min_freq pointer
+        ├── TTLCache    — dict + expiry timestamps
+        └── LRUTTLCache — LRU + TTL combined
+```
+
+The `cache()` decorator handles key generation and cache lookup. The backend handles storage and eviction. Swap the backend, keep everything else.
+
+---
+
+## ⚠️ Known Limitations
+
+- **Caching `None`**: The decorator uses `if cached_res is not None` as the cache-hit check. Functions that legitimately return `None` will always miss — the value won't be cached. Use a sentinel-aware backend or wrap the return value if needed.
+
+---
+
+## 📋 Requirements
+
+- Python 3.12+
+- Courage
+
+---
+
+## 🧪 Development
+
+```bash
+uv sync
+pre-commit install
+
+uv run pytest
+uv run ruff check .
+uv run mypy src/
+uv run mkdocs serve
+```
+
+---
+
+## 📖 Documentation
+
+Full docs at **https://pure-python-system-design.github.io/purecache/**
+
+---
+
+More designs to come, if the pizza supply holds.

purecache-0.1.0/README.md

@@ -0,0 +1,145 @@
+# 🗄️ purecache
+
+Async-native in-memory cache with pluggable eviction backends — pure Python 3.12+, zero dependencies.
+
+Just `asyncio`, `collections.OrderedDict`, and the irrational urge to understand what happens inside the black box.
+
+Part of the [pure-python-system-design](https://github.com/pure-python-system-design) project.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install purecache
+```
+
+Or with uv:
+
+```bash
+uv add purecache
+```
+
+Python 3.12+ required.
+
+---
+
+## ⚡ Quick Start
+
+### Direct backend usage
+
+```python
+from purecache.backends.lru import LRUCache
+
+cache = LRUCache(capacity=128)
+
+await cache.put("user:42", {"name": "Alice"})
+value = await cache.get("user:42")  # {"name": "Alice"}
+value = await cache.get("missing")  # None
+```
+
+### Decorator
+
+```python
+from purecache.decorators import cache
+from purecache.backends.lru import LRUCache
+
+@cache(backend=LRUCache, capacity=128)
+async def get_user(user_id: str) -> dict:
+    return await fetch_from_db(user_id)
+
+# First call — executes get_user, caches result
+user = await get_user("42")
+
+# Second call — returns cached result, skips get_user
+user = await get_user("42")
+```
+
+Cache keys are derived automatically from the function's arguments using `pickle` + SHA-256 — positional args keep their order, keyword args are sorted by name.
+
+---
+
+## 🧠 Backends
+
+| Backend       | Eviction Policy       | Time | Memory | Best For               |
+| ------------- | --------------------- | ---- | ------ | ---------------------- |
+| `LRUCache`    | Least Recently Used   | O(1) | O(n)   | General purpose        |
+| `LFUCache`    | Least Frequently Used | O(1) | O(n)   | Skewed access patterns |
+| `TTLCache`    | Time-based expiry     | O(1) | O(n)   | Sessions, tokens       |
+| `LRUTTLCache` | LRU + TTL combined    | O(1) | O(n)   | Production default     |
+
+All backends implement the `ICacheBackend` protocol — swap them without touching your application code.
+
+---
+
+## 🔌 Framework Examples
+
+The decorator integrates naturally with any async framework:
+
+```python
+# FastAPI
+from fastapi import FastAPI
+from purecache.decorators import cache
+from purecache.backends.lru import LRUCache
+
+app = FastAPI()
+
+@app.get("/user/{user_id}")
+@cache(backend=LRUCache, capacity=512)
+async def get_user(user_id: str):
+    return await fetch_user_from_db(user_id)
+```
+
+TODO: Add more examples for aiohttp, Django, Flask, Litestar, and Sanic in [`examples/`](examples/).
+
+---
+
+## 📐 Architecture
+
+```
+cache() decorator
+  └── ICacheBackend (protocol)
+        ├── LRUCache    — OrderedDict + move_to_end
+        ├── LFUCache    — key_map + freq_map + min_freq pointer
+        ├── TTLCache    — dict + expiry timestamps
+        └── LRUTTLCache — LRU + TTL combined
+```
+
+The `cache()` decorator handles key generation and cache lookup. The backend handles storage and eviction. Swap the backend, keep everything else.
+
+---
+
+## ⚠️ Known Limitations
+
+- **Caching `None`**: The decorator uses `if cached_res is not None` as the cache-hit check. Functions that legitimately return `None` will always miss — the value won't be cached. Use a sentinel-aware backend or wrap the return value if needed.
+
+---
+
+## 📋 Requirements
+
+- Python 3.12+
+- Courage
+
+---
+
+## 🧪 Development
+
+```bash
+uv sync
+pre-commit install
+
+uv run pytest
+uv run ruff check .
+uv run mypy src/
+uv run mkdocs serve
+```
+
+---
+
+## 📖 Documentation
+
+Full docs at **https://pure-python-system-design.github.io/purecache/**
+
+---
+
+More designs to come, if the pizza supply holds.

purecache-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "purecache"
+version = "0.1.0"
+description = "Async-native in-memory cache with pluggable eviction backends. Pure Python, zero dependencies."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = []
+
+authors = [{ name = "Maksim Smirnoff", email = "smirnoffmg@gmail.com" }]
+
+keywords = [
+    "cache",
+    "lru",
+    "lfu",
+    "ttl",
+    "asyncio",
+    "async",
+    "in-memory",
+    "system-design",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/pure-python-system-design/purecache"
+Documentation = "https://pure-python-system-design.github.io/purecache/"
+Repository = "https://github.com/pure-python-system-design/purecache"
+"Bug Tracker" = "https://github.com/pure-python-system-design/purecache/issues"
+Changelog = "https://github.com/pure-python-system-design/purecache/releases"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = [
+    "pytest-asyncio",
+    "ruff",
+    "mypy",
+    "pytest",
+    "pytest-cov",
+    "pre-commit",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+    "pytest-xdist>=3.8.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-benchmark>=5.2.3",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = false
+packages = ["src/purecache"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+pythonpath = ["src"]
+asyncio_mode = "auto"

purecache-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

purecache-0.1.0/src/purecache/__init__.py

@@ -0,0 +1,8 @@
+"""purecache"""
+
+__version__ = "0.1.0"
+
+from .backends import LRUCache
+from .decorators import cache
+
+__all__ = ["cache", "LRUCache"]

purecache-0.1.0/src/purecache/backends/__init__.py

@@ -0,0 +1,3 @@
+from .lru import LRUCache
+
+__all__ = ["LRUCache"]

purecache-0.1.0/src/purecache/backends/lru.py

@@ -0,0 +1,38 @@
+"""LRU Cache — O(1) implementation.
+
+Based on the stack algorithm framework from:
+  "Evaluation Techniques for Storage Hierarchies"
+  R. L. Mattson, J. Gecsei, D. R. Slutz, I. L. Traiger
+  IBM Systems Journal, 9(2):78-117, 1970
+
+  https://dl.acm.org/doi/10.1147/sj.92.0078
+"""
+
+import asyncio
+from collections import OrderedDict
+from typing import Any
+
+
+class LRUCache:
+    def __init__(self, capacity: int):
+        self._capacity = capacity
+        self.container: OrderedDict[str, Any] = OrderedDict()
+        self._lock = asyncio.Lock()
+
+    def _is_full(self) -> bool:
+        return len(self.container) == self._capacity
+
+    async def get(self, key: str) -> Any | None:
+        async with self._lock:
+            if key in self.container:
+                self.container.move_to_end(key, True)
+                return self.container.get(key)
+        return None
+
+    async def put(self, key: str, value: Any) -> None:
+        async with self._lock:
+            if (key not in self.container) and (len(self.container) == self._capacity):
+                self.container.popitem(last=False)  # remove first item
+
+            self.container[key] = value
+            self.container.move_to_end(key, True)  # move to tail

purecache-0.1.0/src/purecache/decorators.py

@@ -0,0 +1,40 @@
+import functools
+import hashlib
+import pickle
+from collections.abc import Callable
+from typing import Any
+
+from .protocols import ICacheBackend
+
+
+def generate_key(args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+    """Build a stable cache key from function args and kwargs.
+
+    - Positional args keep their order (order matters).
+    - Keyword args are sorted by name so call order does not change the key.
+    - Uses pickle to serialize and SHA-256 for a fixed-length key.
+    """
+    canonical = (args, tuple(sorted(kwargs.items())))
+    raw = pickle.dumps(canonical, protocol=pickle.HIGHEST_PROTOCOL)
+    return hashlib.sha256(raw).hexdigest()
+
+
+def cache(
+    func: Callable[..., Any],
+    backend: Callable[..., ICacheBackend],
+    **kwargs: Any,
+):
+    cache_backend = backend(**kwargs)
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        key = generate_key(args, kwargs)
+        cached_res = await cache_backend.get(key)
+        if cached_res is not None:
+            return cached_res
+
+        res = await func(*args, **kwargs)
+        await cache_backend.put(key, res)
+        return res
+
+    return wrapper

purecache-0.1.0/src/purecache/protocols.py

@@ -0,0 +1,6 @@
+from typing import Any, Protocol
+
+
+class ICacheBackend(Protocol):
+    async def get(self, key: str) -> Any | None: ...
+    async def put(self, key: str, value: Any): ...

purecache-0.1.0/src/purecache.egg-info/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: purecache
+Version: 0.1.0
+Summary: Async-native in-memory cache with pluggable eviction backends. Pure Python, zero dependencies.
+Author-email: Maksim Smirnoff <smirnoffmg@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pure-python-system-design/purecache
+Project-URL: Documentation, https://pure-python-system-design.github.io/purecache/
+Project-URL: Repository, https://github.com/pure-python-system-design/purecache
+Project-URL: Bug Tracker, https://github.com/pure-python-system-design/purecache/issues
+Project-URL: Changelog, https://github.com/pure-python-system-design/purecache/releases
+Keywords: cache,lru,lfu,ttl,asyncio,async,in-memory,system-design
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# 🗄️ purecache
+
+Async-native in-memory cache with pluggable eviction backends — pure Python 3.12+, zero dependencies.
+
+Just `asyncio`, `collections.OrderedDict`, and the irrational urge to understand what happens inside the black box.
+
+Part of the [pure-python-system-design](https://github.com/pure-python-system-design) project.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install purecache
+```
+
+Or with uv:
+
+```bash
+uv add purecache
+```
+
+Python 3.12+ required.
+
+---
+
+## ⚡ Quick Start
+
+### Direct backend usage
+
+```python
+from purecache.backends.lru import LRUCache
+
+cache = LRUCache(capacity=128)
+
+await cache.put("user:42", {"name": "Alice"})
+value = await cache.get("user:42")  # {"name": "Alice"}
+value = await cache.get("missing")  # None
+```
+
+### Decorator
+
+```python
+from purecache.decorators import cache
+from purecache.backends.lru import LRUCache
+
+@cache(backend=LRUCache, capacity=128)
+async def get_user(user_id: str) -> dict:
+    return await fetch_from_db(user_id)
+
+# First call — executes get_user, caches result
+user = await get_user("42")
+
+# Second call — returns cached result, skips get_user
+user = await get_user("42")
+```
+
+Cache keys are derived automatically from the function's arguments using `pickle` + SHA-256 — positional args keep their order, keyword args are sorted by name.
+
+---
+
+## 🧠 Backends
+
+| Backend       | Eviction Policy       | Time | Memory | Best For               |
+| ------------- | --------------------- | ---- | ------ | ---------------------- |
+| `LRUCache`    | Least Recently Used   | O(1) | O(n)   | General purpose        |
+| `LFUCache`    | Least Frequently Used | O(1) | O(n)   | Skewed access patterns |
+| `TTLCache`    | Time-based expiry     | O(1) | O(n)   | Sessions, tokens       |
+| `LRUTTLCache` | LRU + TTL combined    | O(1) | O(n)   | Production default     |
+
+All backends implement the `ICacheBackend` protocol — swap them without touching your application code.
+
+---
+
+## 🔌 Framework Examples
+
+The decorator integrates naturally with any async framework:
+
+```python
+# FastAPI
+from fastapi import FastAPI
+from purecache.decorators import cache
+from purecache.backends.lru import LRUCache
+
+app = FastAPI()
+
+@app.get("/user/{user_id}")
+@cache(backend=LRUCache, capacity=512)
+async def get_user(user_id: str):
+    return await fetch_user_from_db(user_id)
+```
+
+TODO: Add more examples for aiohttp, Django, Flask, Litestar, and Sanic in [`examples/`](examples/).
+
+---
+
+## 📐 Architecture
+
+```
+cache() decorator
+  └── ICacheBackend (protocol)
+        ├── LRUCache    — OrderedDict + move_to_end
+        ├── LFUCache    — key_map + freq_map + min_freq pointer
+        ├── TTLCache    — dict + expiry timestamps
+        └── LRUTTLCache — LRU + TTL combined
+```
+
+The `cache()` decorator handles key generation and cache lookup. The backend handles storage and eviction. Swap the backend, keep everything else.
+
+---
+
+## ⚠️ Known Limitations
+
+- **Caching `None`**: The decorator uses `if cached_res is not None` as the cache-hit check. Functions that legitimately return `None` will always miss — the value won't be cached. Use a sentinel-aware backend or wrap the return value if needed.
+
+---
+
+## 📋 Requirements
+
+- Python 3.12+
+- Courage
+
+---
+
+## 🧪 Development
+
+```bash
+uv sync
+pre-commit install
+
+uv run pytest
+uv run ruff check .
+uv run mypy src/
+uv run mkdocs serve
+```
+
+---
+
+## 📖 Documentation
+
+Full docs at **https://pure-python-system-design.github.io/purecache/**
+
+---
+
+More designs to come, if the pizza supply holds.

purecache-0.1.0/src/purecache.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/purecache/__init__.py
+src/purecache/decorators.py
+src/purecache/protocols.py
+src/purecache.egg-info/PKG-INFO
+src/purecache.egg-info/SOURCES.txt
+src/purecache.egg-info/dependency_links.txt
+src/purecache.egg-info/top_level.txt
+src/purecache/backends/__init__.py
+src/purecache/backends/lru.py
+tests/test_decorators.py
+tests/test_lru.py

purecache-0.1.0/src/purecache.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

purecache-0.1.0/src/purecache.egg-info/top_level.txt

@@ -0,0 +1 @@
+purecache

purecache-0.1.0/tests/test_decorators.py

@@ -0,0 +1,324 @@
+"""High-quality tests for purecache.decorators.
+
+Follows Arrange-Act-Assert and the testing pyramid.
+Uses a fake in-memory backend to test decorator behavior without depending on LRUCache.
+"""
+
+import pytest
+
+from purecache.decorators import cache, generate_key
+
+# --- Fake backend for decorator tests ---
+
+
+class FakeBackend:
+    """In-memory backend that records get/put and stores by key."""
+
+    _instances: list["FakeBackend"] = []
+
+    def __init__(self, **kwargs: object) -> None:
+        FakeBackend._instances.append(self)
+        self._store: dict[str, object] = {}
+        self.get_calls: list[str] = []
+        self.put_calls: list[tuple[str, object]] = []
+
+    async def get(self, key: str) -> object | None:
+        self.get_calls.append(key)
+        return self._store.get(key)
+
+    async def put(self, key: str, value: object) -> None:
+        self.put_calls.append((key, value))
+        self._store[key] = value
+
+
+@pytest.fixture(autouse=True)
+def clear_fake_backend_instances() -> None:
+    """Reset so each test gets a clean list of created backends."""
+    FakeBackend._instances.clear()
+    yield
+    FakeBackend._instances.clear()
+
+
+def _get_backend() -> FakeBackend:
+    """Return the backend instance created by the cache decorator."""
+    assert FakeBackend._instances, "No FakeBackend instance created (cache not used?)"
+    return FakeBackend._instances[-1]
+
+
+# --- Unit: generate_key ---
+
+
+def test_generate_key_returns_str() -> None:
+    # Act
+    key = generate_key((1, 2), {"a": 3})
+
+    # Assert
+    assert isinstance(key, str)
+    assert len(key) == 64
+    assert all(c in "0123456789abcdef" for c in key)
+
+
+def test_generate_key_same_args_same_key() -> None:
+    # Arrange
+    args = (1, "x")
+    kwargs = {"a": 10, "b": 20}
+
+    # Act
+    key1 = generate_key(args, kwargs)
+    key2 = generate_key(args, kwargs)
+
+    # Assert
+    assert key1 == key2
+
+
+def test_generate_key_different_args_different_key() -> None:
+    # Act
+    key1 = generate_key((1, 2), {})
+    key2 = generate_key((2, 1), {})
+
+    # Assert
+    assert key1 != key2
+
+
+def test_generate_key_different_kwargs_different_key() -> None:
+    # Act
+    key1 = generate_key((), {"a": 1})
+    key2 = generate_key((), {"a": 2})
+
+    # Assert
+    assert key1 != key2
+
+
+def test_generate_key_kwargs_order_independent() -> None:
+    """Same kwargs in different order produce the same key."""
+    # Act
+    key1 = generate_key((), {"a": 1, "b": 2})
+    key2 = generate_key((), {"b": 2, "a": 1})
+
+    # Assert
+    assert key1 == key2
+
+
+def test_generate_key_positional_order_matters() -> None:
+    # Act
+    key1 = generate_key((1, 2), {})
+    key2 = generate_key((2, 1), {})
+
+    # Assert
+    assert key1 != key2
+
+
+def test_generate_key_empty_args_empty_kwargs() -> None:
+    # Act
+    key = generate_key((), {})
+
+    # Assert
+    assert isinstance(key, str)
+    assert len(key) == 64
+
+
+def test_generate_key_empty_stable() -> None:
+    """Empty args and kwargs produce stable key across calls."""
+    # Act
+    key1 = generate_key((), {})
+    key2 = generate_key((), {})
+
+    # Assert
+    assert key1 == key2
+
+
+def test_generate_key_handles_none_value() -> None:
+    # Act
+    key = generate_key((None,), {"x": None})
+
+    # Assert
+    assert isinstance(key, str)
+    assert len(key) == 64
+
+
+def test_generate_key_handles_list_and_dict() -> None:
+    # Act
+    key = generate_key(([1, 2],), {"k": {"nested": True}})
+
+    # Assert
+    assert isinstance(key, str)
+    assert len(key) == 64
+
+
+def test_generate_key_same_nested_structure_same_key() -> None:
+    # Act
+    key1 = generate_key(({"a": [1, 2]},), {})
+    key2 = generate_key(({"a": [1, 2]},), {})
+
+    # Assert
+    assert key1 == key2
+
+
+# --- Unit: cache decorator (with FakeBackend) ---
+
+
+async def test_cache_miss_returns_func_result() -> None:
+    """On cache miss, wrapper returns the result of the wrapped function."""
+
+    # Arrange
+    async def fn(x: int) -> int:
+        return x + 1
+
+    wrapped = cache(fn, FakeBackend)
+
+    # Act
+    result = await wrapped(10)
+
+    # Assert
+    assert result == 11
+
+
+async def test_cache_miss_calls_backend_get_then_put() -> None:
+    """On cache miss, backend get is called, then put with key and result."""
+
+    # Arrange
+    async def fn(x: int) -> int:
+        return x + 1
+
+    wrapped = cache(fn, FakeBackend)
+
+    # Act
+    await wrapped(5)
+
+    # Assert
+    backend = _get_backend()
+    assert len(backend.get_calls) == 1
+    assert len(backend.put_calls) == 1
+    assert backend.put_calls[0][1] == 6
+
+
+async def test_cache_hit_returns_cached_value_without_calling_func() -> None:
+    """On cache hit, returns cached value and does not call the function again."""
+    # Arrange
+    call_count = 0
+
+    async def fn(x: int) -> int:
+        nonlocal call_count
+        call_count += 1
+        return x * 2
+
+    wrapped = cache(fn, FakeBackend)
+    await wrapped(7)
+
+    # Act
+    result = await wrapped(7)
+
+    # Assert
+    assert result == 14
+    assert call_count == 1
+
+
+async def test_cache_hit_calls_backend_get_only() -> None:
+    """On cache hit, backend get is called once; put is not called again."""
+
+    # Arrange
+    async def fn(x: int) -> int:
+        return x
+
+    wrapped = cache(fn, FakeBackend)
+    await wrapped(1)
+    await wrapped(1)
+
+    # Assert
+    backend = _get_backend()
+    assert len(backend.get_calls) == 2
+    assert len(backend.put_calls) == 1
+
+
+async def test_cache_different_args_different_keys() -> None:
+    """Different (args, kwargs) produce different keys and separate cache entries."""
+
+    # Arrange
+    async def fn(x: int) -> int:
+        return x
+
+    wrapped = cache(fn, FakeBackend)
+    await wrapped(1)
+    await wrapped(2)
+
+    # Assert
+    backend = _get_backend()
+    assert len(backend.put_calls) == 2
+    assert backend.put_calls[0][0] != backend.put_calls[1][0]
+
+
+async def test_cache_same_args_same_key() -> None:
+    """Same (args, kwargs) produce same key so second call is a hit."""
+
+    # Arrange
+    async def fn(x: int) -> int:
+        return x
+
+    wrapped = cache(fn, FakeBackend)
+    key_first = generate_key((1,), {})
+    await wrapped(1)
+
+    backend = _get_backend()
+    key_used = backend.put_calls[0][0]
+
+    # Assert
+    assert key_used == key_first
+
+
+async def test_cache_preserves_function_name() -> None:
+    """Wrapped function preserves __name__ of the original (via functools.wraps)."""
+
+    # Arrange
+    async def my_async_func() -> str:
+        return "ok"
+
+    wrapped = cache(my_async_func, FakeBackend)
+
+    # Assert
+    assert wrapped.__name__ == "my_async_func"
+
+
+async def test_cache_with_kwargs_uses_key_from_both_args_and_kwargs() -> None:
+    """Cache key is derived from both positional and keyword arguments."""
+
+    # Arrange
+    async def fn(a: int, b: int) -> int:
+        return a + b
+
+    wrapped = cache(fn, FakeBackend)
+    await wrapped(1, 2)
+    await wrapped(1, b=2)
+
+    # Assert: (1, 2) vs (1,), {b:2} are different
+    backend = _get_backend()
+    keys = [put[0] for put in backend.put_calls]
+    assert len(keys) == 2
+    assert keys[0] != keys[1]
+
+
+# --- Integration: cache with falsy values ---
+
+
+async def test_cache_stores_falsy_value_then_returns_on_hit() -> None:
+    """Cached value 0 (or other falsy) is returned on second call without calling func.
+
+    Decorator should use 'is not None' (or equivalent) so falsy values are cached.
+    """
+    # Arrange
+    call_count = 0
+
+    async def fn() -> int:
+        nonlocal call_count
+        call_count += 1
+        return 0
+
+    wrapped = cache(fn, FakeBackend)
+    first = await wrapped()
+
+    # Act
+    second = await wrapped()
+
+    # Assert: both return 0; func must be called only once (cache hit on second call)
+    assert first == 0
+    assert second == 0
+    assert call_count == 1

purecache-0.1.0/tests/test_lru.py

@@ -0,0 +1,294 @@
+"""High-quality specification tests for LRUCache.
+
+Follows Arrange-Act-Assert and the testing pyramid:
+- Unit: single operation, one assertion focus.
+- Integration: multiple operations, eviction + ordering behavior.
+"""
+
+import pytest
+
+from purecache.backends.lru import LRUCache
+
+
+@pytest.fixture
+def cache() -> LRUCache:
+    """Fresh LRUCache with capacity 3 per test."""
+    return LRUCache(3)
+
+
+# --- Unit: get behavior ---
+
+
+async def test_get_missing_returns_none(cache: LRUCache) -> None:
+    """get for a key that was never put returns None."""
+    # Arrange: empty cache (fixture)
+
+    # Act
+    result = await cache.get("missing")
+
+    # Assert
+    assert result is None
+
+
+async def test_get_after_put_returns_value(cache: LRUCache) -> None:
+    """After put(key, value), get(key) returns that value."""
+    # Arrange
+    await cache.put("a", 42)
+
+    # Act
+    result = await cache.get("a")
+
+    # Assert
+    assert result == 42
+
+
+async def test_get_after_overwrite_returns_latest_value(cache: LRUCache) -> None:
+    """Two puts for same key; get returns the last value."""
+    # Arrange
+    await cache.put("a", 1)
+    await cache.put("a", 2)
+
+    # Act
+    result = await cache.get("a")
+
+    # Assert
+    assert result == 2
+
+
+# --- Unit: put behavior (no eviction) ---
+
+
+async def test_put_stores_value_by_key(cache: LRUCache) -> None:
+    """put stores value; get with same key returns it."""
+    # Arrange: empty cache
+
+    # Act
+    await cache.put("x", 10)
+
+    # Assert
+    assert await cache.get("x") == 10
+
+
+async def test_put_multiple_keys_stores_independently(cache: LRUCache) -> None:
+    """Several string keys store and retrieve independently."""
+    # Arrange
+    await cache.put("x", 10)
+    await cache.put("y", 20)
+    await cache.put("z", 30)
+
+    # Act
+    x_val = await cache.get("x")
+    y_val = await cache.get("y")
+    z_val = await cache.get("z")
+
+    # Assert
+    assert x_val == 10
+    assert y_val == 20
+    assert z_val == 30
+
+
+# --- Unit: value types (Any) ---
+
+
+async def test_put_get_int_value(cache: LRUCache) -> None:
+    # Arrange
+    await cache.put("k", 1)
+
+    # Act
+    result = await cache.get("k")
+
+    # Assert
+    assert result == 1
+
+
+async def test_put_get_str_value(cache: LRUCache) -> None:
+    # Arrange
+    await cache.put("k", "hello")
+
+    # Act
+    result = await cache.get("k")
+
+    # Assert
+    assert result == "hello"
+
+
+async def test_put_get_dict_value(cache: LRUCache) -> None:
+    # Arrange
+    await cache.put("k", {"nested": True})
+
+    # Act
+    result = await cache.get("k")
+
+    # Assert
+    assert result == {"nested": True}
+
+
+async def test_put_get_none_value(cache: LRUCache) -> None:
+    # Arrange
+    await cache.put("k", None)
+
+    # Act
+    result = await cache.get("k")
+
+    # Assert
+    assert result is None
+
+
+async def test_put_get_object_value(cache: LRUCache) -> None:
+    # Arrange
+    obj = object()
+    await cache.put("k", obj)
+
+    # Act
+    result = await cache.get("k")
+
+    # Assert
+    assert result is obj
+
+
+async def test_put_get_empty_string_key(cache: LRUCache) -> None:
+    """Empty string key is allowed."""
+    # Arrange
+    await cache.put("", "empty")
+
+    # Act
+    result = await cache.get("")
+
+    # Assert
+    assert result == "empty"
+
+
+# --- Unit: capacity 1 ---
+
+
+async def test_capacity_one_put_get_returns_value() -> None:
+    """LRUCache(1): single put then get returns value."""
+    # Arrange
+    cache = LRUCache(1)
+    await cache.put("first", 1)
+
+    # Act
+    result = await cache.get("first")
+
+    # Assert
+    assert result == 1
+
+
+async def test_capacity_one_second_put_evicts_first() -> None:
+    """LRUCache(1): second put evicts first key."""
+    # Arrange
+    cache = LRUCache(1)
+    await cache.put("first", 1)
+    await cache.put("second", 2)
+
+    # Act
+    first_result = await cache.get("first")
+    second_result = await cache.get("second")
+
+    # Assert
+    assert first_result is None
+    assert second_result == 2
+
+
+# --- Integration: eviction and LRU order ---
+
+
+async def test_eviction_removes_oldest_when_at_capacity(cache: LRUCache) -> None:
+    """When at capacity, put of new key evicts the least recently used (oldest)."""
+    # Arrange: fill to capacity
+    await cache.put("a", 1)
+    await cache.put("b", 2)
+    await cache.put("c", 3)
+
+    # Act
+    await cache.put("d", 4)
+
+    # Assert: first key evicted, others and new key present
+    assert await cache.get("a") is None
+    assert await cache.get("b") == 2
+    assert await cache.get("c") == 3
+    assert await cache.get("d") == 4
+
+
+async def test_get_touches_and_protects_from_eviction(cache: LRUCache) -> None:
+    """get(key) refreshes order; that key is not evicted on next insert."""
+    # Arrange
+    await cache.put("a", 1)
+    await cache.put("b", 2)
+    await cache.put("c", 3)
+    await cache.get("a")
+
+    # Act
+    await cache.put("d", 4)
+
+    # Assert: b evicted (second-oldest), a protected by get
+    assert await cache.get("a") == 1
+    assert await cache.get("b") is None
+    assert await cache.get("c") == 3
+    assert await cache.get("d") == 4
+
+
+async def test_put_refreshes_order(cache: LRUCache) -> None:
+    """Overwriting existing key with put counts as recent; not evicted next."""
+    # Arrange
+    await cache.put("a", 1)
+    await cache.put("b", 2)
+    await cache.put("c", 3)
+    await cache.put("a", 10)
+
+    # Act
+    await cache.put("d", 4)
+
+    # Assert: b evicted, a refreshed by overwrite
+    assert await cache.get("a") == 10
+    assert await cache.get("b") is None
+    assert await cache.get("c") == 3
+    assert await cache.get("d") == 4
+
+
+async def test_repeated_put_same_key_keeps_latest_until_evicted(
+    cache: LRUCache,
+) -> None:
+    """Repeated put to same key keeps latest; eviction when others fill capacity."""
+    # Arrange
+    for i in range(10):
+        await cache.put("same", i)
+
+    # Act & Assert: same key still present with latest value
+    assert await cache.get("same") == 9
+
+    # Act: fill capacity with other keys
+    await cache.put("b", 2)
+    await cache.put("c", 3)
+    await cache.put("d", 4)
+
+    # Assert: same evicted, others present
+    assert await cache.get("same") is None
+    assert await cache.get("b") == 2
+    assert await cache.get("c") == 3
+    assert await cache.get("d") == 4
+
+
+async def test_sequential_put_get_ordering(cache: LRUCache) -> None:
+    """Multiple await get/put in sequence behave correctly (no shared state bugs)."""
+    # Arrange & Act: interleaved put/get
+    await cache.put("k1", 1)
+    v1 = await cache.get("k1")
+    await cache.put("k2", 2)
+    v2 = await cache.get("k2")
+    await cache.put("k3", 3)
+    v3 = await cache.get("k3")
+
+    # Assert
+    assert v1 == 1
+    assert v2 == 2
+    assert v3 == 3
+
+    # Act: overflow
+    await cache.put("k4", 4)
+
+    # Assert: k1 evicted (oldest), k2,k3,k4 present
+    assert await cache.get("k1") is None
+    assert await cache.get("k2") == 2
+    assert await cache.get("k3") == 3
+    assert await cache.get("k4") == 4