purecache 0.1.0__py3-none-any.whl

purecache/__init__.py

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

purecache/backends/__init__.py

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

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+purecache/__init__.py,sha256=6YkeKXzH-0onsoLThPb660FJT0dc5FJCNxBu4rQUVBw,134
+purecache/decorators.py,sha256=y3ZQna-P7gdP58M1bqsr-U4OuT2EbDfCHsnc9j7bfVc,1149
+purecache/protocols.py,sha256=Lp2RrTlTuirHY5MLEpcVGkvSlEjD_fOH4xAx4PegmRk,170
+purecache/backends/__init__.py,sha256=rt3kc87jtFzXa_PG9wFA9OtvIXchAOH0M1EQaY3YL7U,50
+purecache/backends/lru.py,sha256=AncdPMFNL6Lksha13xxwyJ11p_5VBzPL4j9KjucpUlI,1223
+purecache-0.1.0.dist-info/METADATA,sha256=X1paAn-dOlb_E9PCSNdwWY3XnQJuBgAABdvWGOnFiJA,4847
+purecache-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+purecache-0.1.0.dist-info/top_level.txt,sha256=T7kG2VnJCUFpcRzjNKTrw7Jx178_u0sNbYL6r5FVVfQ,10
+purecache-0.1.0.dist-info/RECORD,,

purecache-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

purecache-0.1.0.dist-info/top_level.txt

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