如何为cv2与numpy的交互正确添加类型提示？

问题根源 #

你遇到的问题本质是OpenCV的类型存根（type stubs）存在缺陷：

• cv2.typing.MatLike在当前版本的类型定义中被解析为Any，导致imdecode的重载标注虽然写了返回MatLike，但mypy实际识别到的返回类型还是Any。
• 无法直接通过cv2.typing.MatLike访问的问题，是因为该模块的结构限制，必须显式从cv2.typing导入MatLike才能使用。

可行的解决方案 #

方案1：通过类型断言缩小类型范围

在代码中添加类型断言，让mypy明确知道imdecode的返回值是NumPy数组：

import numpy as np
import cv2

def png_to_numpy(blob: bytes) -> np.typing.NDArray[np.uint8]:
    nparr = np.frombuffer(blob, np.uint8)
    img = cv2.imdecode(nparr, cv2.IMREAD_UNCHANGED)
    # 断言返回值为NumPy数组，让mypy识别具体类型
    assert isinstance(img, np.ndarray)
    return img

方案2：显式导入MatLike并转换为明确的NumPy类型

先导入MatLike标注中间变量，再通过np.asarray转换为明确类型：

import numpy as np
import cv2
from cv2.typing import MatLike

def png_to_numpy(blob: bytes) -> np.typing.NDArray[np.uint8]:
    nparr = np.frombuffer(blob, np.uint8)
    img: MatLike = cv2.imdecode(nparr, cv2.IMREAD_UNCHANGED)
    # 转换为明确的uint8类型数组
    return np.asarray(img, dtype=np.uint8)

方案3：临时忽略类型报错（不推荐）

如果不想修改逻辑，可临时添加mypy忽略注释，但这只是权宜之计：

import numpy as np
import cv2

def png_to_numpy(blob: bytes) -> np.typing.NDArray[np.uint8]:
    nparr = np.frombuffer(blob, np.uint8)
    return cv2.imdecode(nparr, cv2.IMREAD_UNCHANGED)  # type: ignore[return-value]

后续处理 #

你向上游仓库提交issue的做法是正确的，这个问题属于OpenCV类型存根的缺陷，需要官方将MatLike的定义从Any调整为np.ndarray | cv2.UMat这类明确的类型联合，才能让mypy正确推导imdecode的返回类型。

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