Why does `weakref.ref()` raise TypeError on an instance of a class declaring `__slots__`?

## Two hidden fields, not one The mental model most people carry is "slots removes the instance dictionary". That is half of it. A plain heap class gives its instances *two* implicit pieces of storage: 1. the per-instance `__dict__`, and 2. a cell holding the weak references that point at the object. `__slots__` opts out of both, because both are storage the class layout would otherwise reserve. Dropping the dictionary is the effect everyone knows; dropping weak-reference support is the one that surfaces later, from somewhere far away in the codebase. ```python import weakref class NoRef: __slots__ = ("value",) weakref.ref(NoRef()) # TypeError: cannot create weak reference to 'NoRef' object ``` ## Why weak references need storage at all A weak reference must be *cleared* when its target is collected, so every live weak reference has to be reachable from the target itself — the object keeps a list of the references aimed at it, and the deallocator walks that list and blanks each one before the memory goes. That list needs a place to live in the instance, and a type that reserved no cell for it cannot support the operation at all. Hence the failure is a `TypeError` about the *type*, raised eagerly, rather than a per-object runtime error. ## The fix, and its one rule List the name explicitly: ```python class WithRef: __slots__ = ("value", "__weakref__") ``` That restores the single cell and nothing else — instances still have no `__dict__` and still reject undeclared names. It is a normal entry in the tuple, so it interacts with inheritance the same way storage does, with one extra constraint: **the cell may exist only once in a hierarchy.** Declaring `"__weakref__"` in a subclass whose base already has it raises `TypeError: __weakref__ slot disallowed: we already got one` at class creation. Declare it on the base that first needs it, and never again below. The corollary catches people the other way round: any slot-less class in the MRO already supplies weak-reference support along with the dictionary, so a slotted class inheriting from a plain base supports `weakref.ref` without declaring anything — and must not declare it, or the class will not build. ## Where it actually bites The failure never appears where the class is defined. It appears the day someone puts your objects into a structure that holds them weakly: a `weakref.WeakValueDictionary` used as an identity cache, a `weakref.WeakSet` of live listeners, an observer registry that must not keep its subscribers alive, or a `weakref.finalize` cleanup hook. The traceback names `weakref`, so people go looking at the cache, when the change that broke it was a declaration added to a data class three modules away for unrelated reasons. The same asymmetry explains a puzzling pair: an old dictionary-backed class works in the cache, a new slotted one raises, and diffing the two classes shows nothing but `__slots__`. ## Deciding what to do about it There are only three honest options. Declare `"__weakref__"` if the objects are meant to be referenced weakly — the cost is one pointer per instance and no loss of the name discipline. Do not declare it if they are not, and let the TypeError document that intent: it is a genuine signal that someone is using the objects in a way the class did not anticipate. Or reconsider the declaration entirely if the objects turn out to be long-lived, registry-managed things rather than the small, numerous records that motivate slots in the first place. What you should not do is add `"__dict__"` to the tuple hoping it fixes the weak-reference error. The two cells are independent: restoring the dictionary does not restore weak-reference support, and you would give up the name discipline for nothing. ## Version note This behaviour, the exact slot name, and the once-per-hierarchy rule are unchanged through Python 3.14.