When would you reach for weakref.WeakKeyDictionary rather than WeakValueDictionary?

### Which side is weak? The two mappings are mirror images and the names say which. `weakref.WeakValueDictionary` holds its keys strongly and its values weakly: it answers "while this object lives, find it by key". `weakref.WeakKeyDictionary` holds its keys weakly and its values strongly: it answers "while this object lives, remember something *about* it". The second is what people call a side table — data attached to an object from the outside, without touching the object at all. ### Why you would want a side table You reach for `WeakKeyDictionary` when you need per-object state and cannot, or should not, store it on the object: * the class is not yours to modify — it comes from a library, or it is a built-in subclass; * the class declares `__slots__`, so you cannot add an attribute at all; * the state is a concern of *your* layer (a parse timestamp, a lock, a computed digest) and putting it on the object would leak your bookkeeping into someone else's type; * several independent subsystems each want their own annotation on the same objects and must not collide in one namespace. The decisive property is lifetime. A plain `dict` keyed by those objects would keep every one of them alive forever — the classic "my annotation table is the leak" bug. With weak keys, the entry evaporates the moment the annotated object is collected, so the table's size tracks the population of live objects automatically and needs no eviction policy of its own. `weakref.WeakSet` is the same idea with no payload: a registry of live members — observers, listeners, open sessions — that never stops any of them from being collected. Iterating it gives you exactly the ones still alive. ### The leak that survives weak keys The one trap worth rehearsing: the *values* of a `WeakKeyDictionary` are strong, so if a value refers back to its own key, the key can never die. The mapping holds the value strongly, the value holds the key strongly, the key therefore has a live strong reference, and the weak key never clears. This is easy to write by accident — storing a small record object that carries a `self.owner` back-pointer, or a closure that captured the key. The fix is either to store only data that does not point back, to store a `weakref.ref` to the key inside the value, or to key on a cheap identifier instead. ### Constraints on the keys A `WeakKeyDictionary` key must satisfy *both* contracts: hashable and weakly referenceable. That excludes `str`, `tuple` and `int` — hashable but not weakly referenceable — and it excludes any unhashable object regardless. In practice keys are user-defined instances, which are hashable by identity by default and weakly referenceable by default, so the two constraints line up. Note that lookup still goes through the key type's `__hash__` and `__eq__`; a `WeakKeyDictionary` is not an identity map unless the key class leaves the default identity-based hashing in place. A class that defines value equality will have two distinct-but-equal keys share one entry, and whichever object dies first can take the entry with it. ### Choosing between the three Ask what you have and what you need: * You have a key and want to find an object that something else keeps alive → `WeakValueDictionary`. * You have an object and want to remember something about it for as long as it lives → `WeakKeyDictionary`. * You have objects and only need to know which of them are still alive → `WeakSet`. * You need the data to *outlive* the object → none of these; use a plain `dict` and take responsibility for eviction. That last line is the one that separates a considered answer from pattern-matching. Weak containers are not "the memory-safe dict"; they are a way of saying "this mapping is a follower, not an owner". If the mapping is genuinely the owner of the data — an audit log, a result you must return later, a counter you will report at shutdown — weakness is the wrong tool and a bounded ordinary container is right. ### Cleanup hooks When you need to *act* at the moment an annotated object goes away rather than merely forget it, pair the mapping with `weakref.finalize(obj, callback, *args)`. It registers a callable to run when the object is collected, it does not resurrect the object, and it is safer than writing `__del__` because it never joins the object into a cycle and its arguments are held explicitly. Take care that the callback's arguments do not include the object itself — that would keep it alive and the finalizer would never fire, which is the same back-reference mistake as above wearing a different hat.