Python 3.12中如何指定多返回类型函数的明确返回值通过mypy检查

给定Python 3.12环境下的函数api_request，它根据as_json参数的布尔值返回requests.Response或dict类型：

import requests

def api_request(*args, as_json: bool = False, **kwargs) -> requests.Response | dict:
    response = requests.request(*args, **kwargs)
    if as_json is True:
        return response.json()
    return response

当调用api_request(..., as_json=True)时，直接使用返回值会触发mypy类型检查错误，显式指定变量类型为dict也会报错；用Any类型或# type:ignore虽能规避错误，但会削弱类型检查的价值。以下是几种在语言层面明确该次调用返回类型的方案：

方案1：使用typing.cast显式类型转换 #

通过cast告诉mypy当前调用的返回类型为dict，仅作用于静态类型检查，不影响运行时逻辑：

from typing import cast

result = cast(dict, api_request("GET", "https://example.com", as_json=True))
# mypy会将result识别为dict类型，不再报错

方案2：重构函数为泛型重载（长期优雅方案） #

利用Python 3.12的泛型与字面量类型特性，通过函数重载让mypy自动根据as_json的取值推断返回类型：

import requests
from typing import overload, Literal

@overload
def api_request(*args, as_json: Literal[False] = ..., **kwargs) -> requests.Response: ...

@overload
def api_request(*args, as_json: Literal[True], **kwargs) -> dict: ...

def api_request(*args, as_json: bool = False, **kwargs):
    response = requests.request(*args, **kwargs)
    if as_json:
        return response.json()
    return response

调用时，传入as_json=True，mypy会自动识别返回类型为dict，无需额外标注。

方案3：使用assert进行类型窄化 #

如果能确保返回值一定是dict，可通过断言让mypy完成类型窄化，同时运行时会验证结果：

result = api_request("GET", "https://example.com", as_json=True)
assert isinstance(result, dict)
# 此后mypy会将result识别为dict类型

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