# 报表函数收到生成器后为什么只能跑一遍：用 types 识别入参

## 文档明确的机制

在报表自动化里，校验函数和汇总函数有时会收到 generator-iterator 对象。Python 标准库 `types` 文档为这类诊断提供了类型名称。

`types.GeneratorType` 是生成器函数创建的 generator-iterator 对象的类型；`types.CoroutineType` 是 `async def` 函数创建的协程对象类型；`types.AsyncGeneratorType` 则是异步生成器函数创建的异步 generator-iterator 对象类型。文档说明，这些标准解释器类型名称的典型用途是 `isinstance()` 或 `issubclass()` 检查。

因此，当报表流程需要判断入参属于哪一类可迭代或异步对象时，可以先用类型判断确认入参是不是 generator-iterator，而不是把类型分歧误判成筛选条件、日期口径或 SQL 结果问题。对于异步链路，还要区分普通协程与异步生成器：前者由 `async def` 创建，后者由异步生成器函数创建，不能用同一种消费方式处理。

`types` 还能帮助识别其他常见入参。`MethodType` 是用户自定义类实例的方法类型；`BuiltinFunctionType` / `BuiltinMethodType` 对应用 C 编写的内建函数和内建类方法，例如文档列出的 `len()`、`sys.exit()`。如果调用方传入的是“取值方法”而不是报表记录，类型诊断应指出这是方法对象，而不是记录集合。

边界值也有明确名称：`NoneType` 是 `None` 的类型；`TracebackType` 是 traceback 对象的类型，可在 `sys.exception().__traceback__` 一类位置见到。前者可用于识别缺失参数，后者更适合错误对象分类，而不是业务数据本身。

另外，`MappingProxyType` 是映射的只读动态视图：底层映射变化时，视图会反映变化；它支持按键访问、迭代键、长度、浅拷贝及视图方法。若报表配置以这种只读代理暴露，诊断时不应把它当作可直接写入的普通字典。`SimpleNamespace` 则提供命名空间属性访问和有意义的 `repr`，可添加、删除属性，也可用关键字参数、单个位置参数或两者混合初始化；文档同时提示，结构化记录类型更适合使用 `namedtuple()`。

## 团队自行约定的接手建议

**以下是团队可自行约定的接手规则，不是 `types` 文档承诺的产品能力。**

第一，诊断结果建议固定输出四项：实际类型名称、是否命中生成器/协程/方法对象等关注类型、是否需要调用方改为团队约定的数据结构、给调用方的修正文案。不要只返回“数据为空”，因为这会掩盖入参实际类型与处理方式不匹配的情况。

第二，若命中 `GeneratorType`，建议由团队约定调用方在进入校验前转换为列表等具体容器，或明确约定只允许一个阶段消费。是否选择转换应由团队根据报表数据规模和接口契约决定；原文只说明生成器对象的类型，不提供自动重放或缓存机制。

第三，命中 `CoroutineType` 或 `AsyncGeneratorType` 时，错误信息建议标明入口位于异步对象，提示调用方检查异步执行链路。不要在类型识别函数里替调用方自动调度任务，因为类型名称只解决“它是什么”，不规定团队的事件循环和异常处理方式。

第四，命中 `MethodType`、`BuiltinFunctionType` 或 `BuiltinMethodType` 时，提示建议写成“收到的是可调用对象/方法对象，请确认是否应先调用并传入结果”。但团队不能仅凭类型就擅自调用：无参方法、带参方法、惰性访问器和有副作用函数之间的差异，需要由业务接口约定。

第五，`NoneType` 可用于区分“未传值”和“空结果”；`TracebackType` 可用于错误归档字段；`MappingProxyType` 可提示只读配置；`SimpleNamespace` 可提示调用方传入的是属性包而非正式记录结构。这些都是诊断标签，不等于字段完整性、数值正确性或权限合法性校验。

## 边界与总结

必须强调，`isinstance()` 类型检查不能替代业务校验。即使对象是列表，也仍可能缺少报表日期、金额字段或维度键；即使对象是 `MappingProxyType`，也只能说明其映射代理机制，不能证明配置内容正确；即使对象不是生成器，也不能仅凭类型判断其是否符合报表流程约定。

版本差异也要以实际运行环境为准。文档列出的若干名称带有新增版本说明，并提醒实例化这些类型时，签名可能随 Python 版本变化。因此，接手脚本应在目标环境中核验可用名称，不能把单一版本文档中的行为无条件推广到旧环境。

综上，`types` 的价值是把报表入参故障从模糊的“拿到一个生成器对象”“拿到一个函数”“异步对象不能这样用”缩小为可记录的类型事实。生成器、协程、异步生成器、方法、内建可调用对象、`None`、traceback、只读映射代理和简单命名空间各有官方用途；而如何缓存、是否调用、怎样接入异步流程，应由团队在不混淆事实与约定的前提下另行规定。

参考来源：Python 3.15.2 官方文档 `types — Dynamic type creation and names for built-in types`，https://docs.python.org/3/library/types.html

## 相关工具

[AI 工作流 ROI 诊断器](/demos/ai-workflow-roi-diagnostic/index.html) · 查看工具的输入要求、输出说明与适用范围。


来源：[报表函数收到生成器后为什么只能跑一遍：用 types 识别生成器、协程和方法对象](https://docs.python.org/3/library/types.html)
