Skip to content

Commit a16ebb0

Browse files
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 passing
1 parent 5726a62 commit a16ebb0

40 files changed

Lines changed: 4049 additions & 3821 deletions

README.md

Lines changed: 379 additions & 370 deletions
Large diffs are not rendered by default.

docs/benchmarking-and-profiling.md

Lines changed: 0 additions & 181 deletions
This file was deleted.

docs/bgcache.md

Lines changed: 0 additions & 149 deletions
This file was deleted.

docs/custom-metrics-exporters.md

Lines changed: 0 additions & 49 deletions
This file was deleted.

0 commit comments

Comments
 (0)