如何为np.nan添加类型提示？函数返回值标注难题求解

针对你遇到的类型提示问题，这里有几种可行的方案：

方案1：结合Union与Literal，补充文档说明 #

由于Literal无法直接包含np.nan（它不属于Python标准字面量范畴），可以用Union[Literal[0, 1], np.float64]作为返回类型标注，同时在函数文档字符串中明确说明返回的np.float64仅为np.nan。这种方式既通过静态类型检查，又能精确描述返回值范围：

import numpy as np
from typing import Literal, Union

def calc_status(raw_value: Union[int, None, float]) -> Union[Literal[0, 1], np.float64]:
    """计算设备状态值
    Args:
        raw_value: 原始输入值，可为整数、None或浮点数
    Returns:
        0（关机）、1（开机）或np.nan（输入无效时）
    """
    if raw_value is None or (isinstance(raw_value, float) and np.isnan(raw_value)):
        return np.nan
    # 其他检查与计算逻辑，确保status为0或1
    status = 1 if raw_value > 0 else 0
    return status

注意：这里修正了输入参数的类型标注——原函数接收None或可能为nan的浮点数，仅标注int会导致类型检查误报。

方案2：使用Annotated添加元数据（Python 3.9+） #

如果使用Python 3.9及以上版本，可借助typing.Annotated为返回的浮点数添加元数据，明确说明仅为np.nan，让类型提示更清晰：

import numpy as np
from typing import Literal, Union, Annotated

def calc_status(raw_value: Union[int, None, float]) -> Union[Literal[0, 1], Annotated[float, "Only np.nan"]]:
    """计算设备状态值
    Args:
        raw_value: 原始输入值，可为整数、None或浮点数
    Returns:
        0（关机）、1（开机）或np.nan（输入无效时）
    """
    if raw_value is None or (isinstance(raw_value, float) and np.isnan(raw_value)):
        return np.nan
    # 其他检查与计算逻辑
    status = 1 if raw_value > 0 else 0
    return status

方案3：自定义类型别名 #

将返回类型封装为自定义别名，可提升代码可读性：

import numpy as np
from typing import Literal, Union

DeviceStatus = Union[Literal[0, 1], np.float64]

def calc_status(raw_value: Union[int, None, float]) -> DeviceStatus:
    """计算设备状态值
    Args:
        raw_value: 原始输入值，可为整数、None或浮点数
    Returns:
        0（关机）、1（开机）或np.nan（输入无效时）
    """
    if raw_value is None or (isinstance(raw_value, float) and np.isnan(raw_value)):
        return np.nan
    # 其他检查与计算逻辑
    status = 1 if raw_value > 0 else 0
    return status

关键说明 #

• np.nan本质是np.float64类型的实例，不属于Python标准字面量，因此无法直接放入Literal中，这也是PyCharm报错的核心原因。
• 输入类型的修正必不可少，否则静态检查会对传入None或浮点型nan的代码抛出类型错误提示。

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