如何告知类型检查器外部函数输出的变量类型

当numpy、scipy这类外部包没有完善的类型提示，导致pyright等检查器无法识别变量类型时，不用修改外部包源码，直接用下面几种方法就能解决：

1. 显式类型标注 #

直接在变量赋值时加上类型注解，让检查器直接采用你指定的类型，忽略它自己的推断结果。这是最直观的方式：

import numpy as np
from scipy.sparse import csr_matrix, spmatrix

def run() -> spmatrix:
    a = csr_matrix(np.eye(3))
    b = csr_matrix(np.eye(3))
    c: spmatrix = a @ b  # 直接标注变量类型
    c = c.multiply(3.0)
    return c

2. 类型断言（Type Casting） #

如果变量已经赋值，后续需要修正类型判断，可以用typing.cast强制告诉检查器变量的真实类型，适合不能在赋值时直接标注的场景：

from typing import cast
import numpy as np
from scipy.sparse import csr_matrix, spmatrix

def run() -> spmatrix:
    a = csr_matrix(np.eye(3))
    b = csr_matrix(np.eye(3))
    c = a @ b
    c = cast(spmatrix, c)  # 断言变量为spmatrix类型
    c = c.multiply(3.0)
    return c

3. pyright专属魔法注释 #

pyright支持用魔法注释覆盖类型推断，除了# type: ignore忽略单行错误，还可以用# type: [类型]精准指定变量类型：

import numpy as np
from scipy.sparse import csr_matrix, spmatrix

def run() -> spmatrix:
    a = csr_matrix(np.eye(3))
    b = csr_matrix(np.eye(3))
    c = a @ b  # type: spmatrix
    c = c.multiply(3.0)
    return c

这种注释只作用于类型检查阶段，完全不影响代码运行。

4. 本地类型存根文件 #

如果项目里很多地方都遇到同一个外部函数的类型问题，可以创建本地类型存根（.pyi文件）补充类型提示。比如在项目根目录下创建scipy/sparse.pyi，补充矩阵乘法的返回类型：

# scipy/sparse.pyi
from typing import TypeVar

T = TypeVar('T', bound='spmatrix')

class spmatrix:
    def __matmul__(self: T, other: T) -> T: ...

存根文件只会被类型检查器读取，不会修改外部包的实际代码，适合批量补充类型的场景。

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