What is the difference between weakref.WeakValueDictionary and WeakKeyDictionary?

Both classes live in `weakref` and both are ordinary mutable mappings you can index, iterate and `len()`. What differs is which side of the entry is a weak reference, and therefore which object's death removes the entry. ### WeakValueDictionary — the mapping does not own the values `weakref.WeakValueDictionary` stores its **values** weakly. Keys are held normally. An entry survives only while somebody else in the process holds a strong reference to the value; when that last holder lets go, the entry is removed automatically. ```python import weakref cache = weakref.WeakValueDictionary() cache['inv-1'] = Invoice(1) # nothing else holds it print(len(cache)) # 0 - already gone keep = Invoice(2) cache['inv-2'] = keep print(len(cache)) # 1 del keep print(len(cache)) # 0 ``` That first line is the whole personality of the class in one statement, and it surprises people constantly. The canonical use is an **identity map**: while any part of the program is working with invoice 42, everyone asking for invoice 42 gets the *same* object; as soon as nobody is working with it, the mapping forgets it. The mapping is an index, never an owner. ### WeakKeyDictionary — the mapping does not own the keys `weakref.WeakKeyDictionary` stores its **keys** weakly and its values strongly. The entry lives as long as the key object lives. This is the *side table*: you want to associate data with objects you did not write and cannot add an attribute to — how many times a connection has been retried, when a customer record was last validated, a per-object lock. A plain `dict` used this way is a permanent leak, because the dict's own reference to the key keeps every object it has ever seen alive for the life of the process. ```python import weakref audit = weakref.WeakKeyDictionary() customer = Customer(7) audit[customer] = 'validated' print(len(audit)) # 1 del customer print(len(audit)) # 0 ``` Two requirements follow from the design. Keys must be **hashable**, like any dict key, and they must be **weak-referenceable**, which rules out `str`, `int`, `tuple` and other builtins whose instances have no `__weakref__` slot. In practice this means the keys are objects, not values — which is exactly right, because a side table keyed by identity is what you wanted. ### WeakSet `weakref.WeakSet` is membership with the same rule: an element is in the set only while something else holds it. It is the natural container for observers and listeners, so that registering for an event does not make the subscriber immortal — a leak that otherwise builds silently every time a short-lived object subscribes and forgets to unsubscribe. `weakref.WeakMethod` completes the picture for bound methods, which would otherwise die immediately because the bound-method object is created fresh on each attribute access. ### The trap: the other half is still strong The most common defect with either class is a strong reference smuggled in through the half you did not make weak. * In a `WeakKeyDictionary`, the **value** is strong. If the value refers back to its key — a wrapper, a closure, a record holding the object — then the mapping keeps the value alive, the value keeps the key alive, and the key never dies. Nothing is ever removed. The entry is self-sustaining and you have rebuilt the leak you were avoiding. * In a `WeakValueDictionary`, the **key** is strong. Values evaporating is the intended behaviour, but the keys accumulate until their entries are removed, so a mapping churned with millions of distinct keys is still doing real work per key. ### Choosing between them Ask who should own the object. If the object's real owner is elsewhere and this mapping is merely an index for looking it up, the values are weak — `WeakValueDictionary`. If the object's real owner is elsewhere and this mapping is annotating it, the keys are weak — `WeakKeyDictionary`. If your mapping is the *only* thing that should keep the object alive, neither is appropriate: use a plain `dict` and decide explicitly when entries leave it. Finally, mutation during iteration is riskier here than with a plain `dict`: entries can vanish between one step of a loop and the next because a collection happened elsewhere, in another thread or simply as a temporary was released. Take a `list()` of the items first when you need a stable snapshot.