1010 ` ruff ` or ` pyright ` .
1111- ** Do not edit ` CHANGELOG.rst ` or bump ` __version__ ` ** ; both are release-only.
1212- ** Pickling caches is unsupported.** It happens to work (` test_pickle* ` ), but the
13- format is an implementation detail that any release may change. Do not document,
14- advertise, or build features on it.
13+ format may change in any release. Do not document, advertise or build on it.
1514- PRs reference an open issue (except trivial fixes), in separate commits:
1615 ` Fix #123: ... ` , ` Tests for #123: ... ` , ` Docs for #123: ... ` .
1716- New behavior needs tests under ` tests/ ` ; user-visible features need docs in
1817 ` docs/index.rst ` (doctested). Keep ` README.rst ` examples in sync with it.
1918- Docs style: two spaces after a sentence; single backticks for parameters and
2019 ` :meth: ` /` :func: ` /` :exc: ` roles in ` docs/index.rst ` , `` double backticks `` in
21- ` CHANGELOG.rst ` . CHANGELOG entries are imperative one-liners without issue numbers,
20+ ` CHANGELOG.rst ` , whose entries are imperative one-liners without issue numbers,
2221 tagged "(breaking change)", "(potentially breaking change)" or "(broken since
23- vX.Y.Z)"; docs-only work is one "Various documentation improvements." line,
24- internal speed-ups without behavior change one "Various performance
25- improvements." line; releases are separated by two blank lines.
26- - Prefer clarity and performance over DRY: the decorator modules duplicate one
27- wrapper per lock/condition/info combination. Apply changes to ** all** variants.
22+ vX.Y.Z)"; docs-only work is one "Various documentation improvements." line, speed-ups
23+ one "Various performance improvements." line; two blank lines between releases.
24+ - Prefer clarity and performance over DRY: the decorator modules duplicate one wrapper
25+ per lock/condition/info combination. Apply changes to ** all** variants.
2826
2927## Architecture
3028
31- ** Caches** (` __init__.py ` ): ` Cache ` is a ` MutableMapping ` with ` maxsize ` , ` currsize `
32- and ` getsizeof ` ; ` maxsize=0 ` and ` math.inf ` are valid, negative values raise
33- ` ValueError ` , and a value's size must not change after insertion. Subclasses override
34- ` __setitem__ ` , ` __delitem__ ` , ` popitem() ` , ` clear() ` and optionally ` __getitem__ ` ,
35- binding parent methods via default parameters (` cache_setitem=Cache.__setitem__ ` ); after
36- the parent ` __getitem__ ` , check the subclass's own bookkeeping (not ` key in self ` ) to
37- handle a ` __missing__ ` that does not store the item. ` popitem() ` reads via
38- ` Cache.__getitem__ ` and evicts via ` del self[key] ` , so subclass ` __delitem__ ` overrides
39- see evictions. ` _TimedCache `
40- (` TTLCache ` , ` TLRUCache ` ) wraps the timer in a re-entrant ` _Timer ` that freezes time
41- per operation; expiry is lazy: ` __len__ ` , ` __repr__ ` and ` currsize ` call ` expire() `
42- first, ` clear() ` does not, and deleting a present-but-expired key removes it and
43- raises ` KeyError ` . ` expire() ` returns the removed ` (key, value) ` pairs.
29+ ** Caches** (` __init__.py ` ): ` Cache ` is a ` MutableMapping ` ; a value's size must not
30+ change after insertion. With the default ` getsizeof ` the private size dict is ` None ` ,
31+ each item counts 1 and ` getsizeof() ` is never called. Subclasses override
32+ ` __setitem__ ` , ` __delitem__ ` , ` popitem() ` , ` clear() ` and optionally ` __getitem__ ` ;
33+ after the parent ` __getitem__ ` , check the subclass's own bookkeeping (not
34+ ` key in self ` ), since ` __missing__ ` may not store the item. ` popitem() ` evicts via ` del self[key] ` , so subclass ` __delitem__ ` overrides
35+ see evictions. ` _TimedCache ` (` TTLCache ` , ` TLRUCache ` ) wraps the timer in a re-entrant
36+ ` _Timer ` that freezes time per operation. Expiry is lazy: ` __len__ ` , ` __repr__ ` and
37+ ` currsize ` call ` expire() ` first, ` clear() ` does not, and deleting a present-but-expired
38+ key removes it and raises ` KeyError ` . ` expire() ` returns early when nothing has expired
39+ and is a documented override hook, so every insert and ` popitem() ` must keep calling
40+ it. Look links/items up with ` .get() ` ; raising ` KeyError ` per new key cost ~ 200 ns.
4441
4542** ` @cached ` ** (` _cached.py ` ): one closure per lock/condition/info combination;
4643` condition ` without ` lock ` serves as both. Call ` functools.update_wrapper() ` * before*
@@ -49,43 +46,35 @@ setting wrapper attributes so stacked decorators keep their state. `info=False`
4946shared by all instances.
5047
5148** ` @cachedmethod ` ** (` _cachedmethod.py ` , ` _descriptor.py ` ): each variant defines a
52- ` Descriptor ` with a nested per-instance ` Wrapper ` , constructed as
53- ` Wrapper(obj, descriptor) ` . ` _MethodDescriptor.__get__ ` stores it in ` obj.__dict__ ` via
54- ` setdefault ` ; wrappers reached through ` super() ` go to
55- ` obj.__dict__["__cachetools_cachedmethods"] ` keyed by descriptor. Class access returns
56- a lazily created ` _Unbound ` callable object, deliberately not a function so
57- ` create_autospec() ` strips the receiver (#443 ); it takes the receiver from ` *args ` or by
58- the wrapped method's first parameter name when passed as a keyword, binds via ` __get__ `
59- when aliased in another class body, and pickles/copies by reference. Pickle/deepcopy
60- (#417 ): ` _WrapperBase.__reduce__ ` returns ` (descriptor.__get__, (obj,)) ` and
61- ` _MethodDescriptor.__reduce__ ` returns ` (_lookup, (owner, attrname)) ` , so wrappers are
62- rebuilt through their descriptor, counters reset, and lock, condition, ` __wrapped__ `
63- and the nested ` Wrapper ` class are never serialized; ` _lookup ` must stay importable and
64- reads the owner's * current* class dict. ` __set_name__ ` on two names, or instances
65- without a writable ` __dict__ ` , raise ` TypeError ` ; ` @classmethod ` use
66- (` _ClassMethodDescriptor ` , ` info=False ` only) and instances without ` __dict__ ` are
67- ** deprecated** and warn instead. Stampede prevention uses a pending set per instance;
68- ` _condition ` 's inner ` wrapper(self, pending, /, ...) ` takes ` pending ` positional-only
69- so a method parameter of that name can be passed by keyword.
49+ ` Descriptor ` with a nested per-instance ` Wrapper(obj, descriptor) ` , stored in
50+ ` obj.__dict__ ` via ` setdefault ` ; ` super() ` lookups use
51+ ` obj.__dict__["__cachetools_cachedmethods"] ` keyed by descriptor. A missing or
52+ read-only ` __dict__ ` raises ` TypeError ` from ` info=True ` descriptors; ` info=False ` ones
53+ (` _ClassMethodDescriptor ` ) warn (` stacklevel=4 ` , at the caller) and run a throwaway
54+ ` Wrapper ` , as does their ** deprecated** ` @classmethod ` use. Class access returns a lazy
55+ ` _Unbound ` callable object, deliberately not a function so ` create_autospec() ` strips
56+ the receiver (#443 ); it takes the receiver positionally or by the wrapped method's first
57+ parameter name. Pickle/deepcopy (#417 ) rebuild wrappers through their descriptor, so
58+ counters reset and nothing unpicklable is serialized; ` _MethodDescriptor._lookup ` must
59+ stay importable. Stampede prevention uses a pending set per instance, passed
60+ positional-only so a method parameter named ` pending ` still works.
7061
7162** Shared** : wrappers swallow ` ValueError ` on store; locked variants release the lock
72- while computing and store via ` setdefault() ` ; the condition tier adds pending keys with
63+ while computing and store via ` setdefault() ` ; the condition tier uses
7364` while k in pending: cond.wait() ` and ` notify_all() ` , so uncontended calls never wait
7465(same-key recursion deadlocks there).
7566
7667** ` func.py ` , ` keys.py ` ** : ` *_cache ` decorators use `cached(..., condition=Condition(),
77- info=True)` plus ` cache_parameters()` ; ` maxsize=None` uses a ` dict` ( ` ttl_cache`:
78- ` _UnboundTTLCache ` ). ` hashkey ` returns a ` _HashedTuple ` using the C tuple hash (a
79- Python-level hash cache was slower; kept commented out with its rationale),
68+ info=True)` ; ` maxsize=None` uses a ` dict` ( ` ttl_cache` : ` _ UnboundTTLCache` ). ` hashkey`
69+ returns a ` _HashedTuple ` using the C tuple hash (a Python-level hash cache was slower),
8070` methodkey ` drops ` self ` , ` typed* ` variants append argument types.
8171
8272## Type Stubs (` *.pyi ` )
8373
8474No annotations in ` .py ` files. ` @overload ` s split ` info=False ` (default, first) and
8575` info=True ` ; wrappers use ` ParamSpec ` , ` _cachedmethod_wrapper ` uses
8676` Concatenate[Any, _P] ` . ` @cached ` wrapper stubs have three ` __get__ ` overloads (class
87- access, instance binding, ` obj: object ` catch-all for ` @staticmethod ` );
88- ` _cached_wrapper_info ` needs a scoped ` # pyright: ignore[reportIncompatibleMethodOverride] ` .
77+ access, instance binding, ` obj: object ` catch-all for ` @staticmethod ` ).
8978` _cachedmethod_unbound.__call__ ` keeps a receiver-less overload for deprecated
9079` @classmethod ` use; ` tests/test_classmethod.py ` must stay type-clean. pyright runs in
9180` standard ` mode with ` reportUnnecessaryTypeIgnoreComment ` ; prefer scoped suppressions.
@@ -100,29 +89,27 @@ tox -e py -- tests/test_ttl.py -k expire # posargs go to pytest
10089- CI runs CPython 3.10–3.15, free-threaded 3.13t–3.15t and PyPy. On 3.13+ two
10190 deprecated ` @classmethod ` lines show as uncovered; the matrix covers them.
10291- ` tests/__init__.py ` has ` CacheTestMixin ` , ` CountedLock ` , ` CountedCondition ` ; one
103- ` TestCase ` per cache type; TTL tests use a manual ` Timer ` .
104- - ` test_cached.py ` /` test_cachedmethod.py ` cover all lock/condition/info combinations.
105- Objects pickled by name must be module-level (` Cached ` , ` CachedChild ` ), not locals.
106- - ` test_func.py ` calls decorators via ` Callable[..., Any] ` ; stub checks need concrete
107- annotated tests (` test_decorator_method* ` ) without ` # type: ignore ` .
108- - ` test_threading.py ` : join with ` TIMEOUT ` and assert threads finished; the condition
109- tests force a contended ` wait() ` , since ` CountedCondition.wait_count ` stays 0 for
110- single-threaded calls.
111- - Performance work: measure with ` timeit ` (best of 7) against a git worktree of the
112- previous release, before and after; keep hot paths free of avoidable Python-level
113- calls, and do not trade documented subclass hooks or semantics for speed.
92+ ` TestCase ` per cache type; TTL tests use a manual ` Timer ` . Objects pickled by name
93+ must be module-level, not locals.
94+ - ` test_func.py ` calls decorators via ` Callable[..., Any] ` , so stub checks need concrete
95+ annotated tests without ` # type: ignore ` (` test_decorator_method ` , ` test_method_typed ` ).
96+ - ` test_threading.py ` : join with ` TIMEOUT ` and assert threads finished; its
97+ ` WaitCondition ` forces a contended ` wait() ` ; single-threaded ` wait_count ` stays 0.
98+ - Performance work: ` timeit ` , best of 7, on a pinned core (` taskset ` ), never in a VM,
99+ against a git worktree of the previous release; keep hot paths free of avoidable
100+ Python-level calls; never trade documented subclass hooks or semantics for speed.
114101
115102## Code Review
116103
117104- Reviews ** amend ` .github/copilot-review.md ` in place** (header: date, commit, CI
118- status, coverage); never new files or dated sections.
105+ status, coverage, one * Verified* paragraph); never new files, dated sections or a
106+ per-commit change summary (git history is the record).
119107- Findings are tables ordered High, Medium, Low, Info with columns
120- ` # | Priority | Location | Finding ` (` Location ` optional); renumber after changes;
121- cross-reference as "Code #3 ", "Docs #2 ". ** Resolved issues are removed** , never
122- marked resolved; git history is the record.
123- - Keep accepted trade-offs as Info rows; record settled matters under * Maintainer
124- Decisions* . State what was verified and how. A review changes nothing; fix only
125- when asked.
108+ ` # | Priority | Location | Finding ` ; renumber after changes; cross-reference as
109+ "Code #3 ". ** Resolved issues are removed** , never marked resolved.
110+ - Keep it brief: one or two sentences per row, numbers only where they decide
111+ something. Keep accepted trade-offs as Info rows; record settled matters under
112+ * Maintainer Decisions* . A review changes nothing; fix only when asked.
126113
127114## Maintainer Decisions (do not re-raise)
128115
@@ -131,10 +118,7 @@ tox -e py -- tests/test_ttl.py -k expire # posargs go to pytest
131118- ` copy.copy() ` of an instance with an active ` @cachedmethod ` wrapper shares the
132119 wrapper; accepted.
133120- Stacking ` @cachedmethod ` decorators is unsupported and untested.
134- - ` super() ` and class access to ` @cachedmethod ` build and discard a ` Wrapper ` per call;
135- accepted (looking up the stored wrapper first was prototyped and declined) .
121+ - Class access to ` @cachedmethod ` ( ` Cls.method(obj, ...) ` ) builds and discards a
122+ ` Wrapper ` per call; accepted .
136123- A ` condition ` must provide the full ` threading.Condition ` interface; ` notify() ` is
137124 reserved for future use. Do not propose relaxing the protocol.
138- - ` TTLCache ` /` TLRUCache ` read the timer through the ` timer ` property, not a cached
139- private attribute (~ 28 ns per hit); evicting-insert overhead in the timed caches is
140- accepted as inherent.
0 commit comments