实用工具和辅助函数

相关源文件

• requirements-dev.lock
• requirements.lock
• src/openai/_compat.py
• src/openai/_types.py
• src/openai/_utils/__init__.py
• src/openai/_utils/_reflection.py
• src/openai/_utils/_sync.py
• src/openai/_utils/_utils.py
• src/openai/lib/streaming/_assistants.py
• tests/utils.py

本文档涵盖了为 OpenAI Python 库提供基础支持的核心实用函数和辅助类。这些实用工具处理类型检查、数据转换、Pydantic 兼容性、异步/同步桥接以及整个代码库中使用的各种专用操作。

有关类型系统架构和生成类型的更多信息，请参阅类型系统架构。有关 Pydantic 模型和数据结构的详细信息，请参阅数据类型和模型。

实用模块组织

这些实用工具分布在几个专门的模块中，提供不同类别的功能

来源: src/openai/_utils/__init__.py1-61 src/openai/_utils/_utils.py1-439 src/openai/_compat.py1-232

核心类型检查和验证

该库提供了一套全面的类型检查实用工具，为标准 Python isinstance 检查提供了类型安全的替代方案

功能	目的	返回类型
is_dict	类型安全的字典检查	TypeGuard[dict[object, object]]
is_list	类型安全的列表检查	TypeGuard[list[object]]
is_mapping	类型安全的映射检查	TypeGuard[Mapping[str, object]]
is_sequence	类型安全的序列检查	TypeGuard[Sequence[object]]
is_given	检查值是否不是 NotGiven	TypeGuard[_T]
is_iterable	类型安全的迭代器检查	TypeGuard[Iterable[object]]

这些类型守卫提供了安全的类型窄化，适用于运行时检查和静态类型检查器。它们通过将容器显式类型化为 dict[unknown, unknown]，避免了 isinstance(obj, dict) 返回 dict[object, object] 的常见陷阱。

来源: src/openai/_utils/_utils.py148-182

数据转换和提取

文件提取系统

函数 extract_files 根据指定路径从嵌套数据结构中递归提取文件

该提取系统会改变原始查询对象，移除文件内容并返回一个扁平化的文件引用列表，用于多部分表单提交。

来源: src/openai/_utils/_utils.py42-132

数据清洗和转换

函数 strip_not_given 从映射中移除 NotGiven 哨兵值，为 API 请求提供干净的数据

函数 deepcopy_minimal 为特定对象类型（映射和列表）提供性能优化的深度复制，而无需 Python 完整 copy.deepcopy 的开销。

来源: src/openai/_utils/_utils.py298-319 src/openai/_utils/_utils.py184-197

Pydantic 兼容层

文件 _compat.py 中的兼容层提供了统一的接口，用于处理 Pydantic v1 和 v2

主要兼容函数包括

• parse_obj() - 统一模型解析
• model_dump() - 统一模型序列化
• get_model_fields() - 访问模型字段定义
• field_is_required() - 字段要求检查
• field_outer_type() - 字段类型提取

来源: src/openai/_compat.py20-177

类型强制转换实用工具

该库提供从字符串值进行安全类型强制转换的功能，并包含可选变体

功能	目的	示例
coerce_integer()	字符串转整数（十进制）	"42" → 42
coerce_float()	字符串转浮点数	"3.14" → 3.14
coerce_boolean()	字符串转布尔值	"true", "1", "on" → True
maybe_coerce_*()	可空变体	None → None

来源: src/openai/_utils/_utils.py321-349

异步/同步桥接实用工具

文件 _sync.py 中的 asyncify 函数将阻塞函数转换为异步等效函数

此实用工具维护上下文变量传播，并通过 sniffio 检测支持 asyncio 和其他异步库。

来源: src/openai/_utils/_sync.py53-87

反射和内省实用工具

函数签名分析

反射实用工具提供了函数内省功能

运行时参数验证

装饰器 required_args 强制对重载函数参数进行运行时验证

来源: src/openai/_utils/_reflection.py1-46 src/openai/_utils/_utils.py219-292

专用辅助函数

客户端检测实用工具

该库提供了用于检测 Azure 客户端实例的专用实用工具

头部处理

函数 get_required_header 提供灵活的头部提取和大小写规范化功能

JSON 安全序列化

函数 json_safe 递归地将数据结构转换为 JSON 可序列化形式，处理如 datetime 对象等特殊类型

来源: src/openai/_utils/_utils.py429-439 src/openai/_utils/_utils.py377-394 src/openai/_utils/_utils.py413-427