直接实现 __contains__ 是最干净的 in 支持方式，因其避免退化为 O(n) 遍历、复用底层 O(1) 查找、确保返回布尔值、适配自定义相等逻辑且行为可控透明。
为什么直接实现 __contains__ 是最干净的 in 支持方式
Python 的 in 操作符默认会先尝试调用对象的 __contains__ 方法；如果没定义，才退化为遍历 __iter__ 或下标访问 __getitem__。这意味着：不实现 __contains__，哪怕你的容器逻辑上支持快速查找（比如底层是 set 或 dict），in 仍可能触发 O(n) 遍历——尤其在数据量大时明显变慢。
常见错误是只重写了 __iter__ 就以为 in 自动高效了，结果性能掉坑里。
- 只要底层有 O(1) 查找能力（如哈希结构），就该显式实现
__contains__ - 避免依赖 fallback 行为，它不可控且不透明
- 若容器逻辑上不支持成员检查（如流式生成器），应显式抛出
TypeError
__contains__ 的参数和返回值必须严格匹配
方法签名固定为 def __contains__(self, item):，且必须返回布尔值。返回非布尔类型（如 int、None）不会报错，但会导致 in 行为异常：Python 把任意真值当 True，比如返回 1 或 "found" 会被接受，但返回 0 或空字符串会被误判为 False，极难调试。
- 务必用
return True/return False，别依赖隐式转换 - 参数
item不做类型预设，需自行处理（比如是否允许None、是否区分大小写） - 若检查逻辑可能抛异常（如 item 类型非法），应在方法内捕获并转为
False或按需抛出
实际例子：用 set 底层实现高效 in 检查
假设你封装一个去重的标签容器，底层用 set 存储：
立即学习“Python免费学习笔记（深入）”；
class TagContainer:
def __init__(self):
self._tags = set()
<pre class="brush:php;toolbar:false;">def add(self, tag):
self._tags.add(tag)
def __contains__(self, tag):
return tag in self._tags # 直接委托给 set.__contains__
这里关键点是：没有手动遍历 self._tags，而是复用 set 原生的 O(1) 成员检查。若误写成 return tag in list(self._tags)，性能立刻退化到 O(n)。
- 优先委托给底层高效结构的
__contains__，而不是“自己动手”遍历 - 若底层是
dict，检查键存在用key in self._data，不是key in self._data.keys()（后者构造新视图，不必要） - 对不可哈希类型（如 dict、list），
set不适用，得换list+ 手动遍历，此时要接受 O(n) 并注明限制
容易被忽略的边界：自定义相等逻辑与 __contains__
如果你的容器元素依赖自定义 __eq__ 判断相等（比如自定义类实例），__contains__ 中的 in 操作会自动调用该逻辑——但前提是底层存储结构也尊重它。例如，把自定义对象存进 set，必须同时实现 __hash__，否则会报 TypeError: unhashable type；而存进 list 则没问题，但 in 会逐个调用 __eq__。
- 仅靠
__eq__不足以让set正常工作，__hash__必须一致（相同对象 hash 值相等，不同对象若__eq__为 True，hash 也必须相等） - 若不想实现
__hash__，又需要高效in，可考虑用dict存 key（value 设为None），因为dict的in检查键也是 O(1)，且不要求 value 可哈希 - 测试时务必覆盖相等但 hash 不同的 case，否则上线后出现“明明相等却 not in”的诡异问题
真正麻烦的从来不是写几行 <strong>contains</strong>，而是底层数据结构的选择和相等性契约的一致性——这两点一旦松动，in 就会悄悄给出错误答案。
