Python中兼容int与NumPy整数数组元素的类型注解写法

现有自定义别名方案评估 #

你当前使用的IntType = Union[int, np.integer]自定义类型别名方案不存在设计缺陷：

• np.integer是所有NumPy整数标量类型的顶层抽象基类，可覆盖np.int8/np.int16/np.int32/np.int64等所有位宽的NumPy单整数值，和Python原生int组成的联合类型完全匹配你的入参场景，类型检查器可正确识别合法入参。
• 该方案的不足是需要自行维护类型别名，没有复用标准库提供的通用抽象，跨项目复用性一般。

更通用的官方推荐写法 #

如果你的运行环境满足Python ≥ 3.8、NumPy ≥ 1.20，可直接使用Python标准库numbers模块中的Integral抽象基类作为类型注解，无需自定义联合类型：

from numbers import Integral

def print_age_in_another_format(age: Integral) -> float:
    ...

这个写法的优势：

• Integral是所有整数类型的通用协议抽象，原生覆盖Python int、所有NumPy整数标量，以及其他第三方库实现的符合整数语义的类型，不需要绑定NumPy做类型联合，通用性更强。
• 属于Python标准库类型，不需要额外维护自定义类型别名，跨项目、跨场景都可以直接使用。

避坑提示 #

• 不要直接用原生int做注解：mypy、pyright等主流类型检查器默认判定np.integer与int类型不兼容，会抛出类型错误，和实际运行时的兼容逻辑不符。
• 如果使用联合类型写法，不要指定具体位宽的NumPy整数类型（比如np.int64），否则其他位宽的NumPy整数传入时会被误判为类型错误，必须使用np.integer这个顶层基类。
• 如果函数内部需要调用仅接收Python原生int的接口，可在函数入口加一行age = int(age)做显式转换，运行时性能损耗极低，可彻底规避边缘场景的类型兼容问题。

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