如何用Python typing模块解决带条件多返回值函数的类型提示问题

错误原因 #

1. 联合类型返回值的问题 #

当给_cast_int_value指定返回类型str | float时，pyright无法确定调用cast_int_to_str时返回的一定是str——联合类型包含两种可能，而cast_int_to_str声明要返回确切的str，因此类型不兼容，触发错误。

2. TypeVar使用的问题 #

你定义的TPossibleCastType是带bound的泛型，但没有将type_cast参数的具体枚举值与返回类型的TypeVar关联起来。TypeCast是枚举类型，其成员是str/float类型本身，但pyright无法自动将枚举成员和TypeVar绑定，导致返回的str/float无法匹配TPossibleCastType。

正确解决方案：使用@overload重载函数 #

通过为_cast_int_value定义多个重载版本，明确不同TypeCast枚举值对应的返回类型，让pyright能根据传入的参数静态推断返回类型：

import enum
from typing import overload, Literal

class TypeCast(str, enum.Enum):
    STRING = str
    FLOAT = float

@overload
def _cast_int_value(value: int, type_cast: Literal[TypeCast.STRING]) -> str:
    ...

@overload
def _cast_int_value(value: int, type_cast: Literal[TypeCast.FLOAT]) -> float:
    ...

def _cast_int_value(value: int, type_cast: TypeCast):
    match type_cast:
        case TypeCast.STRING:
            return str(value)
        case TypeCast.FLOAT:
            return float(value)
        case _:
            raise ValueError(f"Invalid type_cast value: {type_cast}")

def cast_int_to_str(value: int) -> str:
    return _cast_int_value(value, type_cast=TypeCast.STRING)

def cast_int_to_float(value: int) -> float:
    return _cast_int_value(value, type_cast=TypeCast.FLOAT)

原理说明 #

• @overload装饰器为同一个函数定义多个类型签名，对应不同的输入参数组合和返回类型。
• Literal[TypeCast.STRING]明确指定参数必须是TypeCast.STRING这个枚举值，此时pyright会匹配对应的重载，确定返回类型为str；同理，传入TypeCast.FLOAT时返回float。
• 实际实现的_cast_int_value函数保留原有逻辑，重载仅用于类型检查。

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