如何配置basedpyright以正确识别numpy.typing导入？

问题详情 #

在a.py文件中仅写入一行代码：

import numpy.typing as npt

执行poetry run basedpyright a.py时，触发错误：

Import "numpy.typing" could not be resolved (reportMissingImports)

但相同文件使用mypy检测可正常通过。已确认numpy安装目录下存在typing子目录，且basedpyright在其他场景运行正常，仅该导入操作存在问题。

当前项目的pyproject.toml配置如下：

[tool.poetry]
name = "demo"
version = "0.0.1"
description = "This is the python version of the demo package"
authors = ["Come Raczy <come@omtx.ai>"]

[tool.poetry.dependencies]
numpy = ">=2.1.0"
python = ">=3.12,<4.0"

[tool.poetry.group.dev.dependencies]
mypy = ">=1.11.1"
data-science-types = "^0.2.23"
typing-extensions = "^4.12.2"

[tool.mypy]
plugins = "numpy.typing.mypy_plugin"
files = ["."]

[tool.pyright]
typeCheckingMode = "basic"

解决方法 #

1. 升级basedpyright至最新版本 #

numpy 2.x对类型系统做了较大改动，旧版basedpyright可能未适配其typing子模块的导入逻辑。执行命令升级：

poetry add --dev basedpyright@latest

2. 调整导入语法 #

将原导入语句替换为以下形式，部分类型检查工具对这种写法的兼容性更好：

from numpy import typing as npt

3. 配置pyright的额外搜索路径 #

在pyproject.toml的[tool.pyright]区块中添加extraPaths，指定numpy的安装路径（可通过poetry run python -c "import numpy; print(numpy.__path__[0])"获取具体路径）：

[tool.pyright]
typeCheckingMode = "basic"
extraPaths = ["/your/numpy/install/path"]

4. 排查类型定义冲突 #

如果安装了data-science-types，尝试暂时移除该依赖，避免其与numpy自带的类型定义发生冲突：

poetry remove --dev data-science-types

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