如何让类型检查器根据元组布尔元素收窄另一元素类型？

你的问题本质是：类型检查器无法自动关联元组中第一个布尔值和第二个元素的类型依赖——当第一个值为False时第二个必为Exception，为True时必为None。直接用Union或者参数相同的重载都无法让类型检查器正确窄化类型，以下是几种可行的解决方案：

方案1：使用类型守卫函数（保留元组结构） #

定义一个类型守卫函数，显式告诉类型检查器当前分支下元组的具体类型。这种方法可以保留你原本的元组返回格式：

from typing import Literal, Union, TypeGuard

# 定义返回类型的联合
ValidationResult = tuple[Literal[True], None] | tuple[Literal[False], Exception]

# 类型守卫：判断元组是否为失败结果
def is_validation_failure(result: ValidationResult) -> TypeGuard[tuple[Literal[False], Exception]]:
    return not result[0]

def validate(value: MyClass) -> ValidationResult:
    try:
        value.validate()
        return (True, None)
    except Exception as e:
        return (False, e)

def do_something(value: MyClass):
    result = validate(value)
    if is_validation_failure(result):
        # 类型检查器会知道这里result[1]是Exception，不再报错
        raise result[1]
    value.do_something()

针对你提供的简化测试示例，修改后也能正常通过类型检查：

from typing import Literal, reveal_type, TypeGuard

type T = tuple[Literal[True], None] | tuple[Literal[False], Exception]

def is_failure(t: T) -> TypeGuard[tuple[Literal[False], Exception]]:
    return not t[0]

def test(t: T):
    if is_failure(t):
        reveal_type(t[0])  # Literal[False]
        reveal_type(t[1])  # Exception
        raise t[1]  # 无类型错误
    else:
        reveal_type(t[0])  # Literal[True]
        reveal_type(t[1])  # None

方案2：使用带标记的TypedDict（字典格式） #

如果可以接受返回字典而非元组，用TypedDict定义明确的成功/失败结构，类型检查器能自动根据success字段的值推断其他字段的类型：

from typing import TypedDict, Literal, Union

class SuccessResult(TypedDict):
    success: Literal[True]
    error: None

class FailureResult(TypedDict):
    success: Literal[False]
    error: Exception

ValidationResult = Union[SuccessResult, FailureResult]

def validate(value: MyClass) -> ValidationResult:
    try:
        value.validate()
        return {"success": True, "error": None}
    except Exception as e:
        return {"success": False, "error": e}

def do_something(value: MyClass):
    result = validate(value)
    if not result["success"]:
        # 类型检查器自动识别error为Exception
        raise result["error"]
    value.do_something()

方案3：使用自定义数据类（面向对象风格） #

这种方式最清晰，通过不同的类区分成功和失败状态，类型检查器可以通过isinstance直接推断类型：

from dataclasses import dataclass
from typing import Union

@dataclass(frozen=True)
class ValidationSuccess:
    pass

@dataclass(frozen=True)
class ValidationFailure:
    error: Exception

ValidationResult = Union[ValidationSuccess, ValidationFailure]

def validate(value: MyClass) -> ValidationResult:
    try:
        value.validate()
        return ValidationSuccess()
    except Exception as e:
        return ValidationFailure(error=e)

def do_something(value: MyClass):
    result = validate(value)
    if isinstance(result, ValidationFailure):
        raise result.error
    value.do_something()

为什么原重载方案无效？ #

当两个重载的参数列表完全相同时，类型检查器无法根据输入参数区分应该匹配哪个重载，因此会默认选择定义顺序中的第一个重载，导致返回类型被错误推断为(Literal[True], None)。

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