原文链接：Python 的哈希契约：为什么 list 不能当字典的键 - 码日新 · 每日文章

Python 的哈希契约：为什么 list 不能当字典的键

上周帮同事看一个缓存问题：他用列表拼了个 key，运行时直接抛出TypeError: unhashable type: 'list'。改成元组就好了。

但另一个更隐蔽的 bug 是：对象明明还在字典里，却怎么也取不出来。这两个问题其实指向同一条规则——能当字典键的东西，必须遵守哈希契约。

一次d[key]到底发生了什么

Python 的dict本质是哈希表。执行d[key]时，解释器大致做两件事：

1. 计算hash(key)，用结果定位到某个桶；
2. 在桶里用==比较候选键。

为了效率，比较之前还会先看是不是同一个对象；身份相同就直接命中。

classKey:def__init__(self,value):self.value=valuedef__hash__(self):print(f"hash({self.value})")returnhash(self.value)def__eq__(self,other):print(f"eq({self.value},{getattr(other,'value',other)})")returnisinstance(other,Key)andself.value==other.value d={Key(1):"a"}print("--- 查找 ---")print(d[Key(1)])

输出：

hash(1) --- 查找 --- hash(1) eq(1, 1) a

这也解释了字典的两条硬性要求：

• 相等的键必须有相同的哈希；
• 键的哈希在它待在字典里的时候不能变。

违反任何一条，字典就可能找不到东西。

list 不行，tuple 也不一定行

list是可变的，所以 Python 直接把它的__hash__设成了None：

print(list.__hash__)# Noneprint(hash((1,2)))# 正常print(hash((1,[2])))# TypeError: unhashable type: 'list'

元组本身不可变，但它的哈希是由元素组合出来的。只要里面有一个元素不可哈希，整个元组就不可哈希。这个规则会递归传递：

hash((1,(2,3)))# 可以hash((1,(2,[3])))# TypeError

所以“把 list 改成 tuple”并不是万能药。如果列表里还藏着列表或字典，照样会失败。

写了__eq__，__hash__就没了

自定义类默认按身份哈希，也就是基于id()。两个内容相同的对象，默认就是两个不同的键。

一旦你实现了__eq__，Python 会把__hash__置为None，除非你也显式实现它：

classUser:def__init__(self,uid,name):self.uid=uid self.name=namedef__eq__(self,other):returnisinstance(other,User)andself.uid==other.uidprint(User.__hash__)# None# hash(User(1, "a")) # TypeError: unhashable type: 'User'

补上__hash__时，字段必须和__eq__保持一致：

classUser:def__init__(self,uid,name):self.uid=uid self.name=namedef__eq__(self,other):returnisinstance(other,User)andself.uid==other.uiddef__hash__(self):returnhash(self.uid)

这里name可变，但不参与相等判断，也不参与哈希，所以修改它不会破坏字典。

如果整个对象都该不可变，可以用冻结的 dataclass：

fromdataclassesimportdataclass@dataclass(frozen=True)classUser:uid:intname:str

默认的@dataclass(frozen=True)会生成__eq__和__hash__，并阻止属性赋值。注意它的哈希会用到所有参与比较的字段；如果只想按uid判等，还是得手写。

最隐蔽的坑：键被修改了

下面这段代码不会报错，但会让键“消失”：

classMutableKey:def__init__(self,value):self.value=valuedef__hash__(self):returnhash(self.value)def__eq__(self,other):returnisinstance(other,MutableKey)andself.value==other.value k=MutableKey(1)d={k:"one"}k.value=2print(kind)# Falseprint(d.get(k))# Noneprint(list(d))# 键还在字典里print(d[k])# KeyError

字典并没有坏。它只是按照新的哈希去 2 号桶找，而当初存进去的是 1 号桶。旧条目还在，但已经无法通过这个键访问。

解决办法不是“改完再 rehash”，而是别让键变：

• 用不可变对象当键；
• 只把不会变的字段放进__hash__；
• 真需要可变键，就先删除旧键，改完再插回去。

相等但哈希不同，也会出事

还有一种更隐蔽的写法：__eq__按值比较，__hash__却按身份生成。

classBadKey:def__init__(self,value):self.value=valuedef__eq__(self,other):returnisinstance(other,BadKey)andself.value==other.valuedef__hash__(self):returnid(self)a,b=BadKey(1),BadKey(1)print(a==b)# Trueprint(hash(a)==hash(b))# Falsed={a:"a"}print(d[b])# KeyErrorprint(len({a,b}))# 2

两个对象相等，却被放进了不同的桶。字典既无法保证“一个键只出现一次”，也无法通过等价的键找到值。

顺带一提：1、1.0和True

d={1:"int",1.0:"float",True:"bool"}print(d)# {1: 'bool'}

三者相等，哈希也相同，所以它们是同一个键，后写入的覆盖先写入的。这不是 bug，而是哈希契约的正常结果。

NaN 则是另一个极端：

nan=float("nan")d={nan:"x"}print(d[nan])# x，身份相同，直接命中print(d[float("nan")])# KeyError，新对象既不等于自己，哈希也不同

所以别拿 NaN 当键。如果数据里可能出现 NaN，先清洗再入字典。

实践清单

几条可以直接照做的建议：

• 组合键优先用元组；嵌套的 list 转成 tuple，dict 转成tuple(sorted(d.items()))，set 转成frozenset。
• 自定义值对象要同时实现__eq__和__hash__，并保证两者使用同一组字段。
• 对象放进字典后，不要修改参与哈希的字段。
• 需要身份语义时，就用默认的object.__hash__和object.__eq__，不要多写。
• 调试时可以直接打印Cls.__hash__，或者在修改前后对比hash(k)。

回到开头那个缓存：把 list 换成 tuple 只是第一步，真正要确认的是这个 key 在缓存生命周期里不会变。字典不会帮你检查这件事，它只负责按照你给的哈希去找。哈希契约是调用方和维护者之间的约定，Python 把签字笔递给了你。

参考文档

• Primers 编程伙伴/Python/内建函数/type
• Primers 编程伙伴/Python/内建函数/print
• Primers 编程伙伴/Python/内建函数/hash
• Primers 编程伙伴/Python/内建函数/getattr
• Primers 编程伙伴/Python/内建函数/isinstance
• Primers 编程伙伴/Python/内建函数/list
• Primers 编程伙伴/Python/内建函数/int
• Primers 编程伙伴/Python/内建函数/str
• Primers 编程伙伴/Python/内建函数/id
• Primers 编程伙伴/Python/内建函数/len
• Primers 编程伙伴/Python/内建函数/float
• Primers 编程伙伴/Python/内建函数/bool