Commit a16ebb0
committed
feat: clean functional API, pluggable serializers, bg writer/reader, perf + docs
API redesign
- Replaced TTLCache/SWRCache/BGCache class-based API with two symbols: cache() and bg
- @cache(ttl, key=, stale=, store=, metrics=) — TTL and SWR in one decorator
- @bg(interval, key=, ...) — background refresh decoupled from request path
- bg.write / bg.read — single-writer / multi-reader cross-process pattern
- Smart key templates: static 'flags', positional 'user:{}', named 'user:{user_id}'
- .invalidate(*args) and .clear() on every decorated function
Serializers
- New serializers module: Serializer protocol, pack_entry/unpack_entry
- Built-in: json (orjson), pickle, msgpack, protobuf(MyClass)
- Pluggable to all byte-serializing backends (Redis, LocalFile, S3, GCS)
- Custom serializer: implement dumps(v) -> bytes + loads(b) -> object
Storage backends updated
- InMemCache: __slots__, lock-free hot path (GIL atomicity), simplified API
- RedisCache, LocalFileCache, S3Cache, GCSCache: all use pack_entry/unpack_entry
- ChainCache.build(*stores, ttls=[...]) — N-level read-through
- InstrumentedStorage.get_entry forwards optional now= param
Performance
- 23% throughput improvement (91ms -> 69ms per 100k calls)
- TTL-only and SWR code paths split at decoration time (no runtime branch)
- Single time.time() call per cache hit
- Lock-free InMemCache reads; lock only on stale eviction
- bg.read() local hit: ~9M ops/s
bg writer/reader bug fixes (5 bugs)
- Reader job ID collision: unique IDs per bg.read() via _reader_counter
- bg.write and bg.read both missing metrics= parameter — added
- bg.read(store=None) now auto-discovers writer's store in same process
- asyncio.Lock was lazily initialized inside coroutine — fixed to init at registration
- bg.write refresh loop never called metrics.record_background_refresh() — fixed
Docs and examples
- README.md: strong intro, full API reference with examples, single Mermaid diagram
- docs/guide.md: 1022-line unified guide with Mermaid diagrams for every concept
- Deleted 5 stale doc files using old API
- 4 new runnable examples: quickstart, writer_reader, serializers, metrics
- tests/benchmark.py and tests/profile_decorators.py rewritten for new API
- 101 tests passing1 parent 5726a62 commit a16ebb0
40 files changed
Lines changed: 4049 additions & 3821 deletions
File tree
- docs
- examples
- src/advanced_caching
- storage
- tests
Large diffs are not rendered by default.
This file was deleted.
This file was deleted.
This file was deleted.
0 commit comments