Prhub

#39284 [Bugfix][Docs] Fix ReadTheDocs build crash from mocked torch decorator

原始 PR 作者 khluu 合并时间 2026-04-08 17:43 文件变更 1 提交数 2 评论 2 代码增减 +3 / -2

bugfix documentation v1

执行摘要

修复 ReadTheDocs 构建因模拟装饰器 `name` 参数传递错误导致的崩溃。

根据 PR body，ReadTheDocs 构建因 PydanticMagicMock 在初始化时使用 kwargs.pop("name") 提取名称，但未将 name 传递给 MagicMock.__init__，导致 _mock_name = None。当模拟的 @torch.compiler.assume_constant_result 装饰器（在提交 2111997 中添加）在导入期间被使用时，内部调用跟踪执行 _new_parent._mock_name + '.' 时引发 TypeError: unsupported operand type(s) for +: 'NoneType' and 'str'，导致构建崩溃。

该 PR 变更聚焦于文档构建工具链的特定 bugfix，逻辑清晰且影响范围有限。对于关注文档基础设施或模拟类设计的工程师，可精读 PydanticMagicMock 的修改以理解模拟装饰器时的参数传递陷阱。对于大多数开发者，了解修复内容即可，无需深入分析。

讨论亮点

review 评论较少，仅 gemini-code-assist[bot] 指出 PR 更新了 generate_argparse.py 钩子以优化 PydanticMagicMock 初始化和改进错误处理，确保意外错误不被静默忽略。hmellor 直接批准，无具体讨论。

实现拆解

  1. 在 docs/mkdocs/hooks/generate_argparse.py 中修改 PydanticMagicMock.__init__ 方法：将 name = kwargs.pop("name", None) 改为 name = kwargs.get("name")，确保 name 参数同时传递给 MagicMock（用于设置 _mock_name）和 ModuleSpec（用于设置 __spec__）。
  2. 修复 auto_mock 函数中的日志格式字符串：将 logger.exception("Failed to import %s.%s: %s", module_name, attr) 改为 logger.exception("Failed to import %s.%s", module_name, attr)，以匹配占位符数量。
  3. 在 auto_mock 函数中重新抛出非 ModuleNotFoundError 异常，避免静默重试 100 次。
文件 模块 状态 重要度
docs/mkdocs/hooks/generate_argparse.py documentation modified 3.0

分析完成后，这里会展示 LLM 生成的相对完整源码片段和详细注释。

关键符号

PydanticMagicMock.__init__ auto_mock

评论区精华

PydanticMagicMock 初始化中 name 参数传递问题 正确性

PR body 详细解释了 root cause：`kwargs.pop("name")` 导致 `MagicMock.__init__` 未收到 name，进而使 _mock_name 为 None，引发装饰器模拟时的 TypeError。

结论：改为使用 `kwargs.get("name")` 以同时传递 name 给 MagicMock 和 ModuleSpec。 · 已解决

auto_mock 错误处理改进 正确性

修复日志格式字符串占位符不匹配，并确保非 ModuleNotFoundError 异常被重新抛出。

结论：调整日志调用并添加 raise 语句。 · 已解决

风险与影响

  1. 回归风险：修改 PydanticMagicMock.__init__ 中 name 参数的获取方式可能影响其他依赖该模拟类的场景，但风险较低，因为 kwargs.get("name") 仍能正确获取参数且不改变 kwargs 结构。
  2. 兼容性风险：无，修改仅涉及内部模拟逻辑，不影响公共 API。
  3. 性能风险：无，变更微小。
  4. 安全风险：无。
  1. 对用户影响：修复 ReadTheDocs 文档构建崩溃，确保文档能正常生成和发布，提升开发者体验。
  2. 对系统影响：仅影响文档生成流程中的模拟逻辑，不改变运行时行为。
  3. 对团队影响：减少因构建失败导致的维护负担，确保文档持续集成稳定性。
模拟类参数传递错误 日志格式不匹配

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接，后续同步到相关引用后会出现在这里。

完整报告

Markdown PDF

执行摘要

  • 一句话：修复 ReadTheDocs 构建因模拟装饰器 name 参数传递错误导致的崩溃。
  • 推荐动作：该 PR 变更聚焦于文档构建工具链的特定 bugfix，逻辑清晰且影响范围有限。对于关注文档基础设施或模拟类设计的工程师，可精读 PydanticMagicMock 的修改以理解模拟装饰器时的参数传递陷阱。对于大多数开发者，了解修复内容即可，无需深入分析。

功能与动机

根据 PR body，ReadTheDocs 构建因 PydanticMagicMock 在初始化时使用 kwargs.pop("name") 提取名称，但未将 name 传递给 MagicMock.__init__，导致 _mock_name = None。当模拟的 @torch.compiler.assume_constant_result 装饰器（在提交 2111997 中添加）在导入期间被使用时，内部调用跟踪执行 _new_parent._mock_name + '.' 时引发 TypeError: unsupported operand type(s) for +: 'NoneType' and 'str'，导致构建崩溃。

实现拆解

  1. 在 docs/mkdocs/hooks/generate_argparse.py 中修改 PydanticMagicMock.__init__ 方法：将 name = kwargs.pop("name", None) 改为 name = kwargs.get("name")，确保 name 参数同时传递给 MagicMock（用于设置 _mock_name）和 ModuleSpec（用于设置 __spec__）。
  2. 修复 auto_mock 函数中的日志格式字符串：将 logger.exception("Failed to import %s.%s: %s", module_name, attr) 改为 logger.exception("Failed to import %s.%s", module_name, attr)，以匹配占位符数量。
  3. 在 auto_mock 函数中重新抛出非 ModuleNotFoundError 异常，避免静默重试 100 次。

关键文件：

  • docs/mkdocs/hooks/generate_argparse.py（模块 documentation）: 唯一修改的文件，包含修复 PydanticMagicMock 初始化逻辑和 auto_mock 错误处理的核心变更。

关键符号：PydanticMagicMock.init, auto_mock

评论区精华

review 评论较少，仅 gemini-code-assist[bot] 指出 PR 更新了 generate_argparse.py 钩子以优化 PydanticMagicMock 初始化和改进错误处理，确保意外错误不被静默忽略。hmellor 直接批准，无具体讨论。

  • PydanticMagicMock 初始化中 name 参数传递问题 (correctness): 改为使用 kwargs.get("name") 以同时传递 name 给 MagicMock 和 ModuleSpec。
  • auto_mock 错误处理改进 (correctness): 调整日志调用并添加 raise 语句。

风险与影响

  • 风险：1. 回归风险：修改 PydanticMagicMock.__init__ 中 name 参数的获取方式可能影响其他依赖该模拟类的场景，但风险较低，因为 kwargs.get("name") 仍能正确获取参数且不改变 kwargs 结构。
    2. 兼容性风险：无，修改仅涉及内部模拟逻辑，不影响公共 API。
    3. 性能风险：无，变更微小。
    4. 安全风险：无。
  • 影响：1. 对用户影响：修复 ReadTheDocs 文档构建崩溃，确保文档能正常生成和发布，提升开发者体验。
    2. 对系统影响：仅影响文档生成流程中的模拟逻辑，不改变运行时行为。
    3. 对团队影响：减少因构建失败导致的维护负担，确保文档持续集成稳定性。
  • 风险标记：模拟类参数传递错误, 日志格式不匹配

关联脉络

  • PR #39251 [Docs] Update README: 同属文档相关 PR，涉及文档构建或内容更新。
  • PR #39232 [Docs] Add Phi-4-reasoning-vision to supported models + examples: 同属文档相关 PR，关注文档内容扩展。
  • PR #39085 docs: clarify SMT and OMP acronyms in CpuPlatform: 同属文档相关 PR，涉及代码注释澄清。

参与讨论