哈希协议（Hash Protocol）定义对象在哈希表中的行为，使对象能够参与集合操作（set）和字典键（dict）访问，并保证哈希值与相等性的一致性。

一、什么是哈希协议

在 Python 的对象模型中，哈希协议（Hash Protocol）定义了对象可作为哈希表键（如字典 dict、集合 set）的行为规范。

它的核心思想是：

若两个对象相等（a == b），则它们的哈希值必须相同（hash(a) == hash(b)）。

哈希协议使 Python 能够在常数时间内完成字典键查找、集合元素判断等操作。这不仅是性能基础，也是对象一致性的重要语义保障。

二、哈希协议的核心方法

要成为“可哈希对象”（hashable object），一个类必须实现以下方法，并满足一定条件。

（1）__hash__(self)

功能：返回对象的哈希值（一个整数）。

被调用时机：当对象被用于哈希表（如 set 或 dict 键）时，解释器自动调用。

要求：必须返回 int 类型。

若对象在生命周期中可变，则不应实现此方法（否则可能破坏哈希表一致性）。

内建不可变类型如 int、float、str、tuple 等都是可哈希的。

（2）__eq__(self, other)

功能：定义对象的相等性。

关系约束：

若 a == b 为 True，则必须保证 hash(a) == hash(b)。

否则会导致哈希表错误地处理键冲突。

（3）__ne__(self, other)

功能：定义对象的不相等性。可选。

若未定义，Python 将自动根据 __eq__（） 推导。

这三个方法共同定义了对象的哈希一致性契约。

三、哈希协议的内部逻辑

当 Python 在字典或集合中处理键时，大致流程如下：

1、调用 hash(key) 获取哈希值；

2、根据哈希值定位桶（bucket）；

3、若发现哈希冲突，调用 __eq__() 进一步确认对象是否相等；

4、若相等则覆盖旧值，否则插入新键。

示例：

d = {}d["name"] = "Python"print(hash("name"))  # 输出哈希整数print(d["name"])     # 根据哈希快速查找键

Python 保证了：

• 哈希查找的平均时间复杂度为 O(1)；

• 键比较通过 __eq__() 判断语义一致性。

四、示例：自定义可哈希对象

下面示例展示如何编写一个符合哈希协议的自定义类型：

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)                     # 集合中只保留两个不同坐标点

运行结果：

3713081631934410656 3713081631934410656TrueFalse{Point(1, 2), Point(3, 4)}

说明：

• p1 与 p2 具有相同坐标 → 哈希值相同，且视为同一元素；

• p3 坐标不同 → 视为另一对象；

• 集合自动去重，体现了哈希协议的正确性。

五、可变对象与哈希安全性

Python 明确规定：

只有不可变对象（immutable objects）才能可靠地参与哈希运算。

因为哈希表假设键的哈希值在存入后永远不变。

若哈希值在存储后发生改变，查找、删除操作将失败。

举例说明：

# 错误示例：可变对象作为 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.data
key = BadKey([1, 2])d = {key: "value"}
key.data.append(3)  # 修改后 hash 变了！print(d[key])       # KeyError: 查找失败

正确做法是：保持用于哈希的状态不变，或禁止修改。

六、与其他协议的关系

（1）与相等性协议（__eq__）

哈希协议必须与其保持一致性；否则字典或集合会出现逻辑错误。

（2）与容器协议

容器（如 set, dict）依赖哈希协议实现高效成员测试：if x in myset:。

（3）与可变性相关协议

若对象实现了 __setitem__() 或 __delitem__() 等方法，一般不应再实现 __hash__()。

这体现了 Python 数据模型的一致性设计：

只有语义稳定、状态固定的对象才可安全地参与哈希。

📘 小结

哈希协议（Hash Protocol）定义了对象能否安全、高效地作为哈希表键。

其核心约定如下：

__hash__()：返回哈希整数，相等对象哈希必须相同。

__eq__()：判断相等性，决定哈希冲突时的匹配。

__ne__()：可选，判断不等性，通常由 __eq__ 推导。

总结来说：

不可变对象 → 可安全哈希；

可变对象 → 不应定义 __hash__()；

__eq__() 与 __hash__() 必须协同工作。

理解哈希协议，是理解 Python 字典、集合以及对象身份语义的关键一步。它让对象的“逻辑相等性”与“结构稳定性”在语言层面得以统一。

“点赞有美意，赞赏是鼓励”