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免费学习笔记（深入）”；
系统介绍：YIXUNCMS中专专版是易迅软件工作室在中秋节来临之即推出的专题模板建站系统，使用增强版后台管控系统，板板设计符合节日特点。易迅软件工作室恭祝全国人民中秋快乐。特别提示：由于网站页面的不同设计，部分后台功能未在前端进行体现。系统特点：1、采用目前流行的PHP语言编写，底层采用超轻量级框架作为系统支撑；2、页面布局使用DIV+CSS技术，遵循WEB标准，及大提高页面的浏览速度；3、使用应
- 只暴露
__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__ 是否每次都返回干净、独立的新迭代器，决定了它在线程、异步或重入场景下的表现。
