Python C扩展在VS Code中IntelliSense无法正常工作的问题求助

我用C++编写了Python扩展，能够正常导入调用，也可以通过__doc__查看文档字符串，但VS Code的IntelliSense完全无法识别扩展函数：既不显示文档提示，也没有自动补全，悬停函数时仅显示模糊的(function) add_to_tree: Any，而非预期的文档内容。我尝试将编译生成的.so文件路径添加到settings.json的python.analysis.extraPaths中，但问题依然存在。

相关代码文件 #

wrapper.cc（核心扩展代码）

// Function which calls the library or does whatever
static PyObject *foo_wrap(PyObject *self, PyObject *args)
{
    /* Do stuff here */
}


///// Definitions for the extension /////

static PyMethodDef Methods[] = {
    {"foo", foo_wrap, METH_VARARGS, "This is foo's docstring"},
    {NULL, NULL, 0, NULL}
};

static struct PyModuleDef module = {
    PyModuleDef_HEAD_INIT,
    "extension",
    "This is a wrapper for a library",
    -1,
    Methods
};

PyMODINIT_FUNC PyInit_extension(void) {
    return PyModule_Create(&module);
}

setup.py（扩展打包脚本）

from distutils.core import setup, Extension

def main():
    ext = Extension(
        "extension", 
        sources=["wrapper.cc"]
    )

    setup(name="extension",
          version="1.0.0",
          description="This is my extension",
          ext_modules=[ext])

if __name__ == "__main__":
    main()

解决方案 #

1. 手动编写类型存根文件（.pyi） #

VS Code的IntelliSense依赖静态分析，无法直接解析二进制.so文件的内容，因此需要为扩展编写类型存根文件：

• 在扩展所在目录创建extension.pyi文件，内容如下：

  """This is a wrapper for a library"""
  
  def foo(*args) -> Any:
      """This is foo's docstring"""
      ...
  

• 将该.pyi文件放置在与.so相同的目录，或者将其所在路径添加到python.analysis.extraPaths中，重启VS Code即可生效。

2. 改用pybind11生成带类型提示的扩展 #

如果可以替换封装方式，pybind11会自动生成类型信息，无需手动编写存根：

1. 修改setup.py适配pybind11：

   from setuptools import setup, Extension
   import pybind11
   
   ext_modules = [
       Extension(
           "extension",
           sources=["wrapper.cc"],
           include_dirs=[pybind11.get_include()],
           language="c++",
       ),
   ]
   
   setup(
       name="extension",
       version="1.0.0",
       ext_modules=ext_modules,
   )
   

2. 用pybind11风格重写wrapper.cc：

   #include <pybind11/pybind11.h>
   
   namespace py = pybind11;
   
   void foo() {
       /* Do stuff here */
   }
   
   PYBIND11_MODULE(extension, m) {
       m.doc() = "This is a wrapper for a library"; // 模块文档
       m.def("foo", &foo, "This is foo's docstring"); // 函数文档
   }
   

编译完成后，VS Code的IntelliSense会自动识别扩展的类型与文档提示。

3. 调整VS Code Python分析配置 #

确保以下配置正确添加到settings.json：

"python.analysis.packageIndexDepths": [
    {
        "name": "extension",
        "depth": 2
    }
],
"python.analysis.useLibraryCodeForTypes": true

同时确认VS Code右下角状态栏选中的Python解释器是你安装该扩展的版本，之后重启VS Code使配置生效。

内容的提问来源于stack exchange，提问作者V.Iron