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免费学习笔记（深入）”；
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 只暴露
__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)，前提是生产者明确 putNone作为结束信号 - 错误用法：
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__ 是否每次都返回干净、独立的新迭代器，决定了它在线程、异步或重入场景下的表现。
