Python自定义容器协议全解析

本文深入解析了Python中自定义容器的核心机制——容器协议，即通过实现一系列魔术方法（如__len__、__contains__、__getitem__、__setitem__、__delitem__和__iter__）让自定义类自然支持len()、in、索引、切片、迭代、赋值与删除等原生容器操作；文章不仅阐明各方法的职责、调用时机与实现要点（如__len__必须返回非负整数、__getitem__如何统一处理索引与切片、__iter__为何比__getitem__迭代更清晰可控），还结合实用示例揭示协议背后的约定优于强制的设计哲学，帮助开发者写出行为一致、高效且符合Python惯用法的高质量容器类。

Python 中实现自定义容器，核心在于遵循「容器协议」——即实现特定的魔术方法（dunder methods），让类支持常见的容器操作，如 len()、in、索引访问 []、切片、迭代等。这不是语法强制，而是 Python 解释器通过约定俗成的方法名来调用对应行为。

支持长度和成员检测：__len__ 与 __contains__

要让实例能被 len(obj) 调用，必须实现 __len__(self)，返回一个非负整数。注意：不能返回浮点数或负数，否则会触发 TypeError。

支持 item in obj 语法，优先调用 __contains__(self, item)。若未实现，Python 会退而使用迭代（__iter__）逐个比较；但显式实现更高效，尤其对底层是哈希结构（如字典或集合）的容器。

示例：

class SimpleBag:
    def __init__(self, items=None):
        self._items = list(items or [])
<pre class="brush:php;toolbar:false"><code>def __len__(self):
    return len(self._items)

def __contains__(self, item):
    return item in self._items  # 利用列表的 in 实现</code>

支持索引与切片：__getitem__ 是关键

__getitem__(self, key) 是最核心的容器方法之一。它不仅支撑 obj[i]，还自动启用切片 obj[start:stop:step]、迭代（当 key 是 int 且从 0 开始递增时）、以及 for x in obj（只要没定义 __iter__，解释器就用 __getitem__ 模拟迭代）。

处理切片时，key 是 slice 对象，需手动解析 .start、.stop、.step 并返回新容器（通常应返回同类实例，保持接口一致）。

建议：遇到非法索引（如越界整数或不支持的 key 类型）应抛出 IndexError 或 KeyError，而非静默失败。

• 整数索引 → 返回单个元素
• 切片对象 → 返回同类型新实例（如 MyList 切片后仍为 MyList）
• 其他类型（如字符串）→ 可按需支持键访问（类似 dict），但需文档说明

支持可变操作：__setitem__ 和 __delitem__

若希望容器可修改（如 obj[i] = value 或 del obj[i]），还需实现：

• __setitem__(self, key, value)：赋值逻辑，例如检查索引范围、类型约束
• __delitem__(self, key)：删除逻辑，如从内部列表弹出指定位置元素

这两个方法不是必须的——只读容器（如命名元组的模拟）可不实现，此时尝试赋值或删除会触发 TypeError。

注意：__setitem__ 和 __delitem__ 不影响 len() 或 __contains__ 的行为，需确保内部状态同步更新（例如删除后 __len__ 返回值要变）。

支持迭代与解包：__iter__ 更清晰可控

虽然 __getitem__ 能“兼职”迭代，但显式实现 __iter__(self) 更推荐：它明确表达“这是一个可迭代对象”，且可返回任意迭代器（生成器函数、自定义迭代器类、或内置容器的 iter()）。

例如：

def __iter__(self):
    return iter(self._items)  # 直接代理
# 或
def __iter__(self):
    for item in self._items:
        yield item.upper()  # 加工后迭代

有了 __iter__，对象就能用于 for 循环、解包（*obj）、list(obj) 等所有迭代上下文，且不再依赖 __getitem__ 的整数索引模拟。

今天关于《Python自定义容器协议全解析》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！