【合入来源】

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新

【任务背景】

本 PR 对应 pytorch-vllm 开源实习项目中的 Torch-NPU API 一致性对齐任务，公开 issue：
https://gitcode.com/Ascend/pytorch/issues/1628

本 PR 是 v2.12.0 分支的用例补齐 PR，目标是补齐 torch.fx.experimental.symbolic_shapes 下 5 个 API 的直接验证用例。同组交付 PR 如下：

• v2.7.1 用例：https://gitcode.com/Ascend/pytorch/pull/36792
• v2.9.0 用例：https://gitcode.com/Ascend/pytorch/pull/36799
• v2.10.0 用例：https://gitcode.com/Ascend/pytorch/pull/36804
• v2.11.0 用例：https://gitcode.com/Ascend/pytorch/pull/36815
• v2.12.0 用例：https://gitcode.com/Ascend/pytorch/pull/36818
• master 用例：https://gitcode.com/Ascend/pytorch/pull/36820
• 资料支持状态：https://gitcode.com/Ascend/pytorch/pull/36822

【API 功能介绍】

【上游社区测试情况】

已基于当前分支基线检索 test 目录中的相关覆盖情况：

• 上游/基线中存在部分间接覆盖，例如 StatelessSymbolicContext 在 dynamo export/subclass 场景中被使用，ShapeEnvSettings 出现在 public API allowlist 中。
• 未发现覆盖本任务 5 个 API 的集中直接 UT，尤其缺少 ShapeEnv.size_hint、ShapeEnv.suppress_guards、ShapeEnvSettings 字段构造、StatefulSymbolicContext/StatelessSymbolicContext 默认状态的直接行为断言。
• 因此本任务按 issue 要求在 torch-npu test/fx 目录新增自写 UT，而不是搬运现有上游 patch。

【修改方案 / 用例开发思路】

在 test/fx/test_symbolic_shapes_api.py 中新增 5 个直接测试用例：

1. test_shape_env_size_hint：构造 ShapeEnv，验证 sympy.Integer(8) 可返回 size hint 8，并检查签名中包含 expr、allow_none，且 allow_none 默认值为 False。
2. test_shape_env_suppress_guards：验证 ShapeEnv.suppress_guards() 可作为上下文管理器使用，并在上下文内完成 size_hint 求值。
3. test_shape_env_settings：通过 dataclasses.fields 获取当前版本支持字段，只对当前版本存在的字段构造 ShapeEnvSettings，保证跨版本稳定；随后断言配置值可正确保留。
4. test_stateless_symbolic_context：以 DimDynamic.DUCK 构造 StatelessSymbolicContext，验证 dynamic_sizes、默认 dynamic_strides、constraint_sizes、constraint_strides。
5. test_stateful_symbolic_context：以 ConstantSource("x") 构造 StatefulSymbolicContext，验证 tensor_source、空 symbol cache 和动态维配置。

【完备性分析】

• 本 PR 覆盖了 5 个目标 API 的可访问性、核心调用路径、关键返回值、构造参数、默认字段与上下文管理器行为。
• 这 5 个 API 属于 torch.fx.experimental.symbolic_shapes 的 Python 层符号 shape 元信息/上下文能力，不涉及新增 NPU 算子，也不改变跨仓接口或运行时计算逻辑。
• 当前结论：需要新增测试用例，已在本 PR 完成；不需要新增 API 功能实现，不需要新增 NPU kernel，不需要新增资料以外的接口说明。
• 同组 PR 已覆盖 v2.7.1、v2.9.0、v2.10.0、v2.11.0、v2.12.0 和 master；资料支持状态由 PR 36822 单独补齐。

【资料变更】

不涉及。本 PR 仅补充测试用例；资料支持状态已通过独立资料 PR 提交：
https://gitcode.com/Ascend/pytorch/pull/36822

【接口变更】

不涉及。未修改跨仓接口或客户可见接口行为。

【功能验证】

验证新增 5 个目标 API 测试用例，执行命令如下：

cd /workspace/user_data
python3 torch-npu-v2.12.0/test/fx/test_symbolic_shapes_api.py \
  TestSymbolicShapesAPI.test_shape_env_size_hint \
  TestSymbolicShapesAPI.test_shape_env_suppress_guards \
  TestSymbolicShapesAPI.test_shape_env_settings \
  TestSymbolicShapesAPI.test_stateless_symbolic_context \
  TestSymbolicShapesAPI.test_stateful_symbolic_context

执行结果如下：

.....
----------------------------------------------------------------------
Ran 5 tests in 0.034s

OK

【测试效果 / 日志说明】

• 5 个目标 API 用例全部通过。
• 新增用例为 Python 层 symbolic shape 行为验证，测试过程中不依赖新增 NPU 算子实现。
• 当前 PR 已通过 GitCode CI 标签检查：ci-pipeline-passed、docs-ci-pipeline-success。

【CheckList】

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等
• PR持续集成流水线（CI）执行通过，代码检查无异常