Skip to content

Commit 505aece

Browse files
committed
Update copilot instructions and review.
1 parent 2e82602 commit 505aece

2 files changed

Lines changed: 126 additions & 163 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 52 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -10,37 +10,34 @@
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`
4946
shared 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

8474
No 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

Comments
 (0)