Python 迭代协议在框架设计中的应用

python迭代协议要求__iter__必须返回实现了__next__的迭代器对象，否则报typeerror；仅实现__iter__或__next__之一、返回非迭代器、状态未重置、误加__getitem__或__len__等均违反协议。

为什么 __iter__ 和 __next__ 不能只写一半

框架里想让自定义类支持 for 循环或 list() 构造，只实现 __iter__ 却不返回迭代器对象，或者返回了但没实现 __next__，运行时会直接报 TypeError: iter() returned non-iterator of type 'XXX'。

根本原因不是语法错，而是 Python 迭代协议强制要求： __iter__ 必须返回一个实现了 __next__ 的对象（即迭代器），且该对象在耗尽后必须持续抛出 StopIteration。

• __iter__ 返回 self 是最常见做法，但前提是当前类自己实现了 __next__
• 返回 iter(some_list) 或 enumerate(...) 等内置迭代器也合法，此时无需自己写 __next__
• 如果误把生成器函数（含 yield）的返回值当成普通对象直接返回，而没用 return 或 yield from，会导致迭代行为异常——生成器对象本身是迭代器，但它的状态可能未重置

在 fastapi 或 django 中用迭代协议控制序列化输出

很多框架对返回值做隐式序列化（比如 FastAPI 自动调用 jsonable_encoder），如果你返回的是自定义可迭代对象，它可能被当成容器展开，也可能被当成普通对象调用 dict() —— 结果完全取决于框架内部怎么判断“是否可迭代”和“是否映射类型”。

关键点在于：框架通常先检查 isinstance(obj, collections.abc.Iterable)，再决定是否逐项编码。但如果你的类同时实现了 __iter__ 和 __getitem__，某些旧版工具会优先走 __getitem__ 路径，导致下标越界错误。

立即学习“Python免费学习笔记（深入）”；

• 只暴露 __iter__，别加 __getitem__，除非你明确要支持 obj[0] 这种随机访问
• 避免在 __iter__ 里修改实例状态（比如递增计数器），因为同一对象可能被多次迭代（如日志打印、调试器展开）
• FastAPI v0.104+ 对 Iterable 类型做了更严格的检查，若你的类返回的是生成器表达式（(x for x in ...)），它会被识别为 Generator 并正常处理；但若返回的是带状态的生成器函数调用结果（self._gen()），每次迭代都会新建生成器，行为可能不符合预期

iter(obj, sentinel) 在流式响应中的实际用途

Web 框架做 SSE（Server-Sent Events）或长连接流式响应时，常需要从文件、队列或 socket 持续读取数据直到某个结束标记出现。这时内置的双参数 iter() 比手写 while True 更简洁安全。

它本质是不断调用第一个参数（可调用对象），直到返回值等于第二个参数（sentinel），然后抛出 StopIteration。注意：sentinel 必须是能用 == 判断相等的值，不能是 None 以外的单例（比如 Object() 就不行）。

• 读取文件块：iter(Lambda: f.read(8192), b'') —— 空 bytes 表示 EOF
• 从队列取消息：iter(queue.get, None)，前提是生产者明确 put None 作为结束信号
• 错误用法：iter(socket.recv, b'') 可能卡死，因为 recv() 在连接关闭时返回空 bytes，但阻塞模式下也可能因无数据而挂起；应配合 settimeout() 或改用非阻塞 + select

自定义迭代器的 __len__ 和惰性求值冲突

有人会给迭代器加 __len__ 方便前端预估数据量，但这违背迭代协议本意：真正的迭代器是惰性的，长度往往不可知（比如数据库游标、网络流）。一旦你实现了 __len__，某些工具（如 Pydantic v2 的验证逻辑、pandas 的 Series 构造）会尝试调用它，而你的实现若依赖已消费过的迭代状态，就会出错。

更隐蔽的问题是：如果类同时满足 Iterable 和 Sized（有 __len__），一些泛型类型检查（如 typing.Iterable[T] vs typing.Sequence[T]）会误判为可随机访问，导致 ide 提示错误补全或 mypy 报告类型不匹配。

• 真要提供长度，单独加个 .count() 方法，而不是实现 __len__
• 如果必须实现 __len__（比如兼容某老库），确保它不依赖迭代过程中的任何中间状态，且文档注明“该长度仅反映初始快照”
• 测试时用 collections.abc.Iterator 显式检查：isinstance(obj, collections.abc.Iterator)，比 hasattr(obj, '__iter__') 更准确

迭代协议看着简单，但框架层会层层叠加类型推断、序列化策略和生命周期管理。最容易被忽略的是：同一个对象在不同上下文中可能被多次 iter()，而你写的 __iter__ 是否每次都返回干净、独立的新迭代器，决定了它在线程、异步或重入场景下的表现。