如何为NumPy数组添加正确的Mypy类型注解？

针对你使用的Mypy 0.910和NumPy 1.23.1版本，以下是正确的类型注解方法，以及解决检查失效问题的方案：

1. 正确的注解写法 #

方法一：使用numpy.typing.NDArray（推荐简化写法） #

npt.NDArray的类型参数需传入元素类型对应的dtype类型，结合显式指定dtype参数使用，能让Mypy准确识别类型：

import numpy as np
import numpy.typing as npt

# 整数数组注解
a: npt.NDArray[np.int64] = np.array([0, 1, 2], dtype=np.int64)
# 浮点数数组注解
b: npt.NDArray[np.float64] = np.array([0.1, 0.2, 0.3])

方法二：直接使用np.ndarray（完整泛型写法） #

np.ndarray的泛型参数格式为[ShapeType, DtypeType]，其中第二个参数必须是np.dtype[T]的形式：

from typing import Any
import numpy as np

# 任意形状的整数数组
a: np.ndarray[Any, np.dtype[np.int64]] = np.array([0, 1, 2], dtype=np.int64)
# 明确形状的一维浮点数数组
b: np.ndarray[tuple[int, ...], np.dtype[np.float64]] = np.array([0.1, 0.2, 0.3])

2. 解决Mypy不报错的问题 #

你遇到的npt.NDArray[np.int64]赋值浮点数数组却无报错的情况，主要原因有两个：

• NumPy类型推断限制：旧版本NumPy对np.array的自动dtype推断支持有限，Mypy无法准确识别未指定dtype时的数组元素类型。解决办法是显式指定dtype参数，让注解与实际类型严格匹配。
• Mypy配置未开启严格检查：默认配置下Mypy的类型兼容性检查不够严格，需在mypy.ini或pyproject.toml中开启相关选项：

  [mypy]
  strict = True
  disallow_incomplete_defs = True
  numpy_stubs = True
  

  开启strict模式后，Mypy会严格校验数组类型与注解的匹配，比如a: npt.NDArray[np.int64] = np.array([0.1, 0.2, 0.3])会直接触发类型不兼容错误。

3. 你之前写法报错的原因 #

你尝试的np.ndarray[Any, np.int64]写法错误，因为np.ndarray的第二个泛型参数要求是np.dtype[T]类型，而非直接传入np.int64（这是dtype实例的类型别名）。正确写法应为np.ndarray[Any, np.dtype[np.int64]]。

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