哈希协议（Hash Protocol）是 Python 在处理对象散列计算与哈希表定位时所遵循的一套核心规则。它规定了解释器在遇到 hash(obj)、对象作为 dict 键或 set 元素等语境时，应当如何判定对象是否可哈希，以及在判定成立后，沿何种路径取得其哈希值。
理解可哈希性与哈希协议，是为了把握 Python 如何在保持“值相等”语义一致的前提下，使对象能够安全、稳定地参与基于哈希表的高效索引与集合运算。
一、可哈希性与哈希协议
在 Python 中，一个对象若满足以下条件，则称为“可哈希”（hashable）：
• 对象的类型对象在其哈希槽位中提供了有效实现
• hash(obj) 返回一个整数
• 若 a == b，则必须保证 hash(a) == hash(b)
• 在对象生命周期内，其哈希值保持稳定
在 Python 中，以下语境会触发哈希协议：
• 显式调用 hash(obj)
• 将对象作为 dict 的键
• 将对象加入 set 或 frozenset
• 在基于哈希表实现的容器（dict、set、frozenset）进行成员测试时
例如：
在 Python 的对象模型中，哈希协议定义了对象可作为散列表键的行为规范。哈希协议的核心方法只有一个：
语义要求：
• 返回一个整数（int）
• 在对象生命周期内保持不变
• 与相等性语义保持一致
该方法在类体执行阶段创建为函数对象，存储于类对象字典中。它不会通过普通属性查找机制被触发，而是通过类型对象的哈希槽位参与分派。
哈希协议使 Python 能够在常数时间内完成字典键查找、集合元素判断等操作。这不仅是性能基础，也是对象一致性的重要语义保障。
二、散列语境的解释路径
所谓散列语境（hashing context，也称“哈希上下文”），是指解释器在某种语言结构或运行路径中，需要根据对象的哈希值来进行定位或判定的执行环境。
以如下表达式为例：
当解释器执行字典键值对绑定操作时，将触发一次完整的散列语境解释路径。
基本过程如下：
1、解释器进入字典的键值对绑定逻辑，触发哈希协议。
2、读取 type(a) 的哈希槽位（在 CPython 中为 tp_hash）。
3、若该槽位为 NULL（例如类定义了 __hash__ = None），则抛出：
TypeError: unhashable type
否则，调用该入口，取得整数哈希值：
语义上等价于：
4、根据哈希值 h 计算散列表中的初始槽位。
说明：CPython 的具体实现采用开放寻址与扰动探测算法，此处仅说明语义层逻辑。
5、若该散列表槽位已被占用，则解释器触发相等性规则（__eq__）：
若 a == existing_key，则视为语义上同一键，覆盖其对应的值。
6、若不相等，则根据冲突解决算法继续探测下一个散列表槽位。
在最终确定的散列表槽位处，将键 a 与值 1 绑定存储。
说明：
（1）在语言语义层面，散列表定位规则与相等性协同关系构成哈希协议语义约束的一部分。
（2）显式调用 hash(a) 本质上触发的是同一分派路径。
（3）哈希协议属于单向分派机制，不存在反向路径，不存在子类优先规则，也不存在双向协商。
三、自定义哈希语义
哈希协议允许用户通过定义 __hash__ 参与哈希语义的建立。
例如：
class Point: def __init__(self, x, y): self.x = x self.y = y def __eq__(self, other): # 定义相等性：坐标相同即认为相等 if isinstance(other, Point): return self.x == other.x and self.y == other.y return NotImplemented def __hash__(self): # 返回基于坐标的哈希值 # 使用 tuple 的哈希计算，保证稳定性 return hash((self.x, self.y)) def __repr__(self): return f"Point({self.x}, {self.y})"
使用：
p1 = Point(1, 2)p2 = Point(1, 2)p3 = Point(3, 4)print(hash(p1), hash(p2)) # 哈希值相同print(p1 == p2) # Trueprint(p1 == p3) # Falses = {p1, p2, p3}print(s) # 集合中只保留两个不同坐标点
自定义哈希并不是“给对象添加可放入字典的能力”，而是在散列语境下，为解释器提供一个可被选中的协议入口。
Python 对哈希协议还存在一条重要的自动规则：
若类定义了 __eq__，但未定义 __hash__，则解释器会将 __hash__ 设为 None，该对象将变为不可哈希类型。
示例：
class A: def __eq__(self, other): return Truea = A()hash(a) # TypeError
这是为了避免破坏“相等对象必须具有相同哈希值”的一致性原则，即：若 a == b 为 True，则必须保证 hash(a) == hash(b)。
因此，若希望恢复哈希能力，必须显式定义 __hash__。
四、实例属性不会影响哈希协议
与多数协议一致，哈希协议的判定发生在类型层面，而不是实例字典。
例如：
class A: passa = A()a.__hash__ = lambda: 123hash(a) # 仍然使用 A.__hash__
尽管实例 a 拥有名为 __hash__ 的属性，解释器在哈希语境中不会通过普通属性访问机制进行判定，而是读取类型层的哈希入口。
A.__hash__ 来自其基类 object.__hash__，通过继承机制获得，并在类型对象的哈希槽位中生效。
因此，可哈希性来自类型结构，而非实例属性。
五、哈希协议与不可变对象
散列表在设计上假设：键在存入后，其哈希值在整个生命周期内保持稳定。
若哈希值发生改变，原有槽位无法正确定位，查找与删除操作可能失败，散列表语义被破坏。
因此，实践中通常只对不可变对象（immutable objects）实现哈希语义。
例如：
hash(42)hash("python")hash((1, 2, 3))
这些类型的状态在生命周期内不会改变，因此其哈希值稳定。
可变对象的风险示例：
# 错误示例：可变对象作为 dict 键class BadKey: def __init__(self, data): self.data = data def __hash__(self): return hash(tuple(self.data)) # 基于可变列表计算哈希 def __eq__(self, other): return self.data == other.datakey = BadKey([1, 2])d = {key: "value"}key.data.append(3) # 修改后 hash 变了！print(d[key]) # KeyError: 查找失败
该对象技术上可哈希，但其哈希语义不稳定，因此违反散列表假设。
六、哈希协议的典型应用场景
哈希协议贯穿 Python 的多个核心机制。
1、字典键定位
2、集合元素管理
3、成员测试（x in container）
4、缓存结构（如 lru_cache）
5、去重逻辑
6、不可变对象建模
这些场景的共同点在于：对象并未“执行哈希”，而是在散列语境下，被解释器按协议规则解释为可参与哈希定位的对象。
📘 小结
哈希协议是解释器在散列语境中所采用的类型分派规则。它通过类型对象的哈希入口，将对象映射为稳定整数，并要求该映射与相等语义保持一致，从而保证基于哈希表的数据结构在语义与性能上的可靠性。对象的可哈希性并非名称属性，而是类型结构满足协议约束后的结果。
