frozenset and Element Hashability

### The rule behind the rule A `set` is a hash table. When an object goes in, CPython calls `hash()` on it, reduces the result to a slot index, and parks the object in that slot. When you later ask `x in s`, the interpreter hashes `x`, jumps straight to that slot, and uses `==` only against the handful of objects that happened to land in the same place. That is the whole source of the near-constant-time membership test, and it holds together on one assumption: **the hash of a stored object never changes while it is stored.** So every element of a `set` — and every key of a `dict` — must be *hashable*: it must have a working `__hash__`, and that value must stay fixed for the object's lifetime. ### Why the mutable built-ins are excluded Python's mutable containers define equality by content: two distinct list objects holding `[1, 2]` compare equal. Hashing carries a hard invariant — objects that compare equal must hash equal — so a content-based `__eq__` forces a content-based hash, and a content-based hash changes the moment you append. An object like that in a hash table becomes unreachable: it sits in the slot its old hash chose while every lookup goes to the slot its new hash chooses. Rather than let you build that quietly broken structure, CPython sets `__hash__` to `None` on `list`, `dict`, `set` and `bytearray`. The result is a loud failure at insertion time instead of a silent lookup miss much later. ### What 3.14 changed about the message The rule is as old as sets, but the diagnostics improved. On 3.14, building `{[1, 2]}` reports `cannot use 'list' as a set element (unhashable type: 'list')`, and `{[1, 2]: 3}` reports `cannot use 'list' as a dict key (...)`. On 3.13 and earlier both said only `unhashable type: 'list'`, which named the culprit but not the context. A bare `hash([1, 2])` still produces the short form on 3.14, because there is no container to name. ### Hashability is recursive It is not a property of the outermost type. A `tuple` computes its hash by combining its elements' hashes, so `(1, 2)` is hashable and `(1, [2])` is not — the inner list has no hash to combine. The same applies to `frozenset`: `frozenset([[1]])` fails to construct. When you convert data at a boundary to make it set-worthy, you have to convert all the way down, not just the top level. ### Enter frozenset `frozenset` is the built-in immutable set. It takes any iterable, deduplicates by hash and equality exactly as `set` does, supports every read operation `set` supports, and simply has no mutating methods. Because its membership is fixed at construction, it can safely publish a `__hash__` derived from its members' hashes — and it does so order-independently, so `frozenset({1, 2})` and `frozenset({2, 1})` are equal and hash identically. That single property unlocks the three things a plain `set` cannot do: * be an element of another set, which is how you build a set of sets; * be a key in a `dict`; * be an argument to anything that hashes its inputs, such as a memoizing decorator. ```python groups = {frozenset({"a", "b"}), frozenset({"c"})} print(frozenset({"b", "a"}) in groups) # True routes = {frozenset({"billing"}): "finance-queue"} print(routes[frozenset(["billing", "billing"])]) # finance-queue ``` ### Two sharp edges First, `set` and `frozenset` compare equal whenever they hold the same members — `frozenset({1, 2}) == {1, 2}` is `True`. Equality was never the constraint; hashability is. So a dict keyed on a frozenset cannot be looked up with the equal plain set: `d[{1, 2}]` raises `cannot use 'set' as a dict key (unhashable type: 'set')`. Second, set *containment* special-cases this. `{1} in {frozenset({1})}` returns `True`, because when a set's membership test receives an unhashable `set`, CPython retries with a temporary frozenset copy instead of raising; `remove` and `discard` do the same. It is a convenience limited to those three set methods, and it does not extend to dict lookups — which is exactly why the two behaviours look inconsistent from the outside. ### Doing it in real code The practical move is to convert once, at the point where data enters the hashed structure: build a `tuple` from a list of coordinates before collecting points in a set, build a `frozenset` from a collection of labels before using it as a key. Converting at the boundary keeps the mutable, ergonomic form in the code that manipulates the data, and the frozen, hashable form in the code that indexes it.