如何为pybind11生成的.pyd模块启用Visual Studio Intellisense

背景 #

已在Visual Studio 2022的MSBuild项目中成功使用pybind11将C/C++函数打包为可直接导入Python的.pyd库。

问题描述 #

在VS2022中编写导入该.pyd库的.py文件时，Intellisense仅能识别库存在（无导入报错下划线），但无法识别模块内容，无法提供函数、符号、签名等自动补全提示。

诉求 #

1. 能否通过配置项或在C/C++代码的PYBIND11_MODULE()段添加内容，让Intellisense像识别.py模块一样提供该.pyd模块的详细提示？
2. VS Code或CMake项目中是否存在同类问题及类似解决方案？

一、Visual Studio 2022 MSBuild项目处理方式 #

1. 生成类型存根文件（.pyi） #

这是最可靠的方案，为.pyd模块创建对应的类型存根文件后，Intellisense会自动读取并提供补全：

• 手动编写：根据pybind11绑定的函数、类结构，编写与模块同名的.pyi文件，示例：

  # my_module.pyi
  def add(a: int, b: int) -> int: ...
  class MyClass:
      def __init__(self, value: int) -> None: ...
      def get_value(self) -> int: ...
  

• 自动生成：使用pybind11-stubgen工具自动生成存根，安装后执行命令：

  pybind11-stubgen my_module
  

  将生成的存根文件放在.pyd模块同目录即可。

2. 配置Visual Studio IntelliSense设置 #

• 打开工具 > 选项 > Python > IntelliSense，勾选“使用完整的IntelliSense引擎”。
• 将.pyd模块所在目录添加到Python项目搜索路径：右键Python项目 > 属性 > 搜索路径 > 添加目标文件夹。

3. 为pybind11绑定代码添加注释 #

在PYBIND11_MODULE段中为函数、类添加文档字符串，辅助存根生成工具生成更准确的类型提示，示例：

PYBIND11_MODULE(my_module, m) {
    m.doc() = "pybind11 example module";

    m.def("add", &add, "Add two integers",
          py::arg("a"), py::arg("b"));

    py::class_<MyClass>(m, "MyClass")
        .def(py::init<int>(), "Initialize with an integer value")
        .def("get_value", &MyClass::get_value, "Return the stored value");
}

二、VS Code中的同类问题解决 #

VS Code的Python插件同样无法直接识别.pyd模块内容，解决方案如下：

1. 生成.pyi类型存根文件（方法同VS2022）。
2. 在settings.json中配置模块路径：

   {
       "python.analysis.extraPaths": ["./path/to/pyd_modules"]
   }
   

3. 重启Python语言服务：按下Ctrl+Shift+P，执行Python: Restart Language Server。

三、CMake项目中的处理 #

在CMake项目中可通过脚本自动生成存根，避免手动操作：

1. 确保项目使用的Python环境已安装pybind11-stubgen。
2. 在CMakeLists.txt中添加自定义编译后步骤：

   add_custom_command(TARGET my_module POST_BUILD
       COMMAND ${PYTHON_EXECUTABLE} -m pybind11-stubgen my_module
       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
       COMMENT "Generating stub files for my_module"
   )
   

   每次编译完成后会自动生成存根，Intellisense即可识别模块内容。

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