__iter__ 必须返回迭代器对象(实现__next__),而非self或可迭代对象;否则无法支持多次独立遍历、与内置函数兼容,且易破坏迭代协议。

为什么 __iter__ 必须返回迭代器,而不是直接返回 self
很多初学者写自定义类时,会直接在 __iter__ 里用 yield 或返回一个列表,结果发现多次遍历失败、或与内置函数(如 list()、sum())行为不一致。根本原因是:迭代协议要求 __iter__ 返回一个**迭代器对象**(即实现了 __next__ 的对象),而不是可迭代对象本身。
如果返回 self,那这个类就必须同时实现 __next__,且要能维护内部状态(比如当前索引)。否则第二次 for 循环就会从头开始,或抛出 StopIteration 后永远卡住。
实操建议:
- 若数据结构天然支持“重放”(如列表、元组),优先返回新生成的迭代器(例如
iter(self._data)或用生成器函数) - 若需保持状态(如流式读取、单次消费场景),才让
self同时充当可迭代对象和迭代器——但必须在__iter__中重置状态(如self._index = 0) - 避免在
__iter__中返回[x for x in ...]这类一次性列表——它虽可迭代,但不是迭代器;且会提前耗尽内存
用生成器函数实现 __iter__ 最安全
生成器函数(含 yield)天然返回迭代器,状态由 Python 运行时管理,不易出错,也符合“一次一值”的迭代语义。
立即学习“Python免费学习笔记(深入)”;
比如实现一个只读的二维坐标容器:
class PointCollection:
def __init__(self, points):
self._points = points # list of (x, y)
<pre class="brush:php;toolbar:false;">def __iter__(self):
for x, y in self._points:
yield (x, y) # 自动包装成 generator object
这样就能直接用于 for p in points:、list(points)、max(points, key=lambda p: p[0]) 等所有标准迭代场景。
注意点:
- 不要在生成器里修改
self._points—— 迭代期间修改底层数据容易引发RuntimeError: dictionary changed size during iteration类似问题 - 如果想支持反向迭代,额外实现
__reversed__,别依赖reversed()对生成器的默认行为(它会先转成列表) - 生成器无法被
len()调用,若需长度支持,得单独实现__len__
当需要支持 next() 和手动控制时,必须分离迭代器类
如果自定义结构要支持多路并发迭代(比如两个 for 循环同时遍历同一个对象),就不能让 self 兼任迭代器——因为状态会互相干扰。
正确做法是把迭代逻辑抽到独立类中:
class PointIterator:
def __init__(self, collection):
self._collection = collection
self._index = 0
<pre class="brush:php;toolbar:false;">def __iter__(self):
return self
def __next__(self):
if self._index >= len(self._collection._points):
raise StopIteration
point = self._collection._points[self._index]
self._index += 1
return pointclass PointCollection: def init(self, points): self._points = points
def __iter__(self):
return PointIterator(self)
这样每次调用 __iter__ 都创建新迭代器实例,彼此状态隔离。
常见坑:
- 忘记在
__next__中抛StopIteration—— 导致无限循环 - 在
PointIterator.__next__中直接访问self._collection._points[self._index]却没做越界检查 —— 抛IndexError而非StopIteration,破坏协议 - 把迭代器类写成闭包或嵌套函数——无法被 pickle,也不利于调试
测试是否真正符合迭代协议:三步验证法
光看能不能 for 循环不够。真正合规要过三关:
- 能被
iter(obj)正常调用,且返回对象有__next__方法 - 该返回对象能被多次
next()调用,直到抛StopIteration - 同一个对象能被多个独立
iter()调用,各自走自己的进度
快速验证示例:
obj = PointCollection([(1,2), (3,4)]) it1 = iter(obj) it2 = iter(obj) print(next(it1)) # (1, 2) print(next(it2)) # (1, 2) —— 不受 it1 影响 print(next(it1)) # (3, 4)
如果第二行输出不是 (1, 2),说明迭代器没隔离;如果第三行报错或重复输出,说明状态没重置或越界处理不对。
最易被忽略的是「多迭代器并存」这一条——很多看似工作的实现,在真实业务中遇到 zip(a, b) 或 itertools.chain() 就崩,根源就在这儿。


















