如何根据函数参数的实际字面值精确推断返回类型

python 类型检查器（如 pyright）可通过 `@overload` 结合 `literal` 类型，基于字符串参数的**具体字面值**（如 `"r"` 或 `"rb"`）为函数提供精准的、分支化的返回类型提示，而非仅依赖运行时类型。

在静态类型检查中，仅用 str 作为参数类型（如 mode: str）会导致类型信息丢失——因为 str 是宽泛类型，无法表达 "r" 和 "rb" 在语义和行为上的根本差异。而 open() 这类内置函数之所以能实现“根据字面值返回不同类型”，其背后并非魔法，而是通过显式重载声明 + 字面量类型约束实现的。

核心方案是组合使用 @typing.overload 与 typing.Literal。Literal 允许将字符串参数限定为若干个编译期已知的具体值，@overload 则为每组字面量组合声明独立的函数签名。类型检查器据此进行精确匹配：

from typing import overload, Literal, Any, IO, Optional
from io import TextIOWrapper, BufferedReader, BufferedWriter, BytesIO

# 定义模式字面量类型（提升可读性与复用性）
TextReadModes = Literal["r", "r+", "rt", "rt+"]
TextWriteModes = Literal["w", "w+", "wt", "wt+"]
BinaryReadModes = Literal["rb", "rb+"]
BinaryWriteModes = Literal["wb", "wb+"]

@overload
def open(
    file: str,
    mode: TextReadModes = ...,
    buffering: int = ...,
    encoding: Optional[str] = ...,
    errors: Optional[str] = ...,
    newline: Optional[str] = ...,
) -> TextIOWrapper: ...

@overload
def open(
    file: str,
    mode: TextWriteModes,
    buffering: int = ...,
    encoding: Optional[str] = ...,
    errors: Optional[str] = ...,
    newline: Optional[str] = ...,
) -> TextIOWrapper: ...

@overload
def open(
    file: str,
    mode: BinaryReadModes,
    buffering: int = ...,
    encoding: None = ...,
    errors: None = ...,
    newline: None = ...,
) -> BufferedReader: ...

@overload
def open(
    file: str,
    mode: BinaryWriteModes,
    buffering: int = ...,
    encoding: None = ...,
    errors: None = ...,
    newline: None = ...,
) -> BufferedWriter: ...

# 最终实现签名（运行时逻辑，不参与类型检查）
def open(
    file: str,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    closefd: bool = True,
    opener: Any = None,
) -> IO[Any]:
    # 实际调用内置 open —— 此处仅为类型存根示例
    ...

✅ 关键说明：

• @overload 装饰的函数仅用于类型检查，不包含实现体（即无函数体，只写 ...）；
• 所有重载必须在最终的非 @overload 函数定义之前声明；
• Literal["r", "rb"] 告诉类型检查器：“这个参数只能是这些确切字符串之一”，从而启用精确路径推断；
• Pyright 对 open 的智能推断并非硬编码，而是严格遵循标准库 typeshed 中提供的上述重载定义（位于 stdlib/io.pyi）；
• 当你传入变量（如 mode = "rb"）时，Pyright 若能证明该变量是不可变字面量常量（PEP 675 中的 literal type narrowing），仍可推断；但若来自函数参数（如 def f(mode: str)），则因 str 类型过宽而退化为 IO[Any] —— 这正是类型安全的设计取舍。

? 实践建议：

• 自定义类似函数时，优先使用 Literal + @overload 构建多态接口；
• 避免用 Union[TextIOWrapper, BufferedReader] 替代重载 —— 它会丧失调用端的类型精度（例如 .read().upper() 将报错）；
• 可配合 TypeVar 与 Literal 进一步泛化（如绑定 mode 与 return_type 的协变关系），但多数场景 overload 已足够清晰有力。

这一体系体现了 Python 类型系统“渐进式精确化”的设计哲学：在不破坏动态特性的前提下，通过声明式提示赋予工具链强大的推理能力。