如何从RevitAPI.dll生成适用于代码检查的高质量Python类型存根？

针对RevitAPI这类复杂.NET程序集，要生成能满足代码检查需求的高质量Python类型存根，目前有一套经过验证的工具链和优化步骤，可解决接口、枚举、迭代器等类型的注册问题：

主流工具选择 #

• clr-stub-generator：专门为.NET程序集生成Python类型存根的工具，对Revit API兼容性最佳。它能直接解析.NET元数据，自动识别接口、枚举、泛型类型及迭代器实现。
  使用示例命令：

  clr-stub-generator --include-interfaces --include-generics -o ./revit_stubs RevitAPI.dll RevitAPIUI.dll
  

  注意必须同时传入RevitAPIUI.dll及其他依赖的系统程序集（如System.dll），否则会丢失大量关联类型。
• pyright 结合元数据解析：pyright本身支持读取.NET程序集元数据，可通过配置pyrightconfig.json指定程序集路径，再用pyright --stub命令生成存根。适合已用pyright做代码检查的场景，但需额外配置处理.NET特有的泛型和接口。

关键优化配置 #

• 强制加载所有依赖：RevitAPI.dll依赖多个.NET程序集，生成存根时必须将这些依赖文件放在同一目录或通过命令参数指定路径，避免类型缺失。
• 启用完整类型解析：对于clr-stub-generator，添加--include-interfaces和--include-generics参数，确保接口（如IExternalCommand）、泛型集合（如IList<Element>）被完整生成。
• 迭代器类型补全：针对Revit API中返回迭代器的类型（如FilteredElementCollector），工具会自动生成__iter__方法并标注返回的元素类型，示例如下：

  def __iter__(self) -> Iterator[Autodesk.Revit.DB.Element]: ...
  

  确保代码检查工具能识别迭代返回的元素类型。

接口、枚举、迭代器的针对性处理 #

• 枚举：工具会自动从.NET元数据中提取所有枚举成员及对应值，生成标准Python枚举类，比如BuiltInCategory会包含所有Revit内置类别常量，无需手动补充。
• 接口：生成的存根会保留接口的抽象方法签名，比如IExternalCommand.Execute的参数和返回值类型会严格匹配Revit API定义，代码检查工具能据此验证接口实现是否合规。
• 迭代器与集合：针对.NET集合的双迭代实现（IEnumerable的__iter__和GetEnumerator()），存根会同时覆盖两种方法，确保编辑器和代码检查工具能正确识别迭代行为。

存根质量验证 #

• 用pyright或mypy运行代码检查，确认是否还存在未识别的类型、参数不匹配等提示。
• 对照Revit API官方文档，抽查存根中的方法签名、枚举值是否与官方定义一致。
• 在VS Code等编辑器中测试代码补全和实时检查，确保调用Revit API时能正确提示参数类型，且类型错误能被及时捕获。

内容的提问来源于stack exchange，提问作者bb197