VSCode如何实现独立目录下Pants生成的_pb2模块自动补全

问题说明 #

使用Pants管理基于Protocol Buffers的Python项目时，Pants自动生成的_pb2.py、_pb2.pyi文件会存放在独立的dist/codegen目录树中，项目目录结构如下：

.
|-- dist/
|   `-- codegen/
|       `-- src/
|           `-- project/
|               |-- data_pb2.py
|               `-- data_pb2.pyi
`-- src/
    `-- project/
        |-- __init__.py
        |-- code.py
        `-- data.proto

业务代码code.py中存在导入语句from project import data_pb2，在settings.json中配置python.analysis.extraPaths = ["dist/codegen/src"]后，Pylance不再提示模块缺失，但自动补全始终无法生效，Pylance读取不到data_pb2的成员类型信息。

根因 #

Pylance默认将dist、build这类常见构建产物目录加入索引排除列表，就算路径被加入extraPaths，目录下的.pyi类型文件也不会被扫描索引，自然无法提供类型提示和补全。除此之外，相对路径解析错误、生成代码目录缺少包标记文件也会导致同类问题。

修复步骤 #

• 修改项目根目录下.vscode/settings.json配置，先把Pants生成代码的目录从Pylance默认排除规则里豁免：

{
    "python.analysis.exclude": [
        "!dist/codegen/**"
    ],
    "python.analysis.extraPaths": [
        "${workspaceFolder}/dist/codegen/src"
    ],
    "python.analysis.useLibraryCodeForTypes": true
}

extraPaths必须用${workspaceFolder}拼接成工作区绝对路径，不要直接写相对路径，避免多工作区场景下路径解析错位；useLibraryCodeForTypes默认值为true，如果之前手动关过这个配置，必须改回开启状态，否则Pylance不会加载.pyi文件的类型信息。

• 检查dist/codegen/src/project目录下是否存在空的__init__.py文件，不存在就手动创建。Pants默认不会给生成的代码目录生成包标记文件，缺少该文件时Pylance会将对应目录识别为命名空间包，会出现类型索引异常。如果不想每次清理dist目录后手动重建，可以加一个Pants构建后置钩子自动生成这个空文件。
• 配置完成后按快捷键Ctrl+Shift+P（macOS系统用Cmd+Shift+P）唤起命令面板，执行Python: Restart Language Server命令重启Pylance服务，等待索引完成后自动补全即可恢复正常。

排查技巧：重启语言服务后可以打开Pylance的输出面板，查看索引日志中是否存在dist/codegen/src/project/data_pb2.pyi的扫描记录，存在该记录即说明配置生效。

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