如何根据函数参数的具体字面值（而非仅类型）精确推断返回类型

python 类型检查器（如 pyright）可通过 `@overload` 结合 `literal` 类型，基于字符串字面量参数（如 `"r"` 或 `"rb"`）精准推断不同返回类型，而非退化为宽泛的 `io[any]`。

在静态类型检查中，仅依赖参数类型（如 str）往往不足以表达行为差异——例如 open() 函数的返回类型实际由 mode 参数的具体字面值决定："r" 对应 TextIOWrapper，"rb" 对应 BufferedReader。标准类型提示无法用普通泛型（如 TypeVar）捕获这种“值相关”的类型分支，因为 TypeVar 只能约束类型，不能绑定运行时字面量。

解决方案是使用 @overload 装饰器配合 Literal 类型，为每组有意义的字面量组合显式声明重载签名：

from typing import overload, Literal, Any
from io import TextIOWrapper, BufferedReader, BufferedWriter, TextIOWrapper

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

@overload
def open(
    file: str | bytes,
    mode: TextReadModes = ...,
    buffering: int = ...,
    encoding: str | None = ...,
    errors: str | None = ...,
    newline: str | None = ...,
) -> TextIOWrapper: ...

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

@overload
def open(
    file: str | bytes,
    mode: TextWriteModes,
    buffering: int = ...,
    encoding: str | None = ...,
    errors: str | None = ...,
    newline: str | None = ...,
) -> TextIOWrapper: ...

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

# 实际实现（运行时逻辑，不参与类型检查）
def open(
    file: str | bytes,
    mode: str = "r",
    buffering: int = -1,
    encoding: str | None = None,
    errors: str | None = None,
    newline: str | None = None,
    closefd: bool = True,
    opener: Any = None,
) -> Any:
    # 此处为实际内置 open 的调用逻辑（省略）
    ...

✅ 关键机制说明：

• Literal["r", "rb"] 表示该参数必须且只能是这些确切字符串字面量，类型检查器据此缩小可能分支；
• @overload 告诉检查器：当调用符合某条签名时，就采用其声明的返回类型；
• Pyright（及 mypy 0.990+）原生支持此模式，因此 open("f.txt", "rb") 被推断为 BufferedReader，而 open("f.txt", mode)（mode: str）因失去字面量信息，回退为 IO[Any] —— 这正是你观察到的行为差异根源，并非“硬编码”，而是对标准库 open 的规范重载实现（CPython 的 typeshed 提供了完整 overload 声明）。

⚠️ 注意事项：

• Literal 仅适用于编译期已知的字面量（如 "r"、42、True），变量引用（如 mode = "rb"; open(..., mode)）若未被常量折叠，可能仍触发宽泛类型；
• 所有 @overload 声明必须位于实际实现函数之前，且实现函数本身不带类型注解（或仅用最宽泛类型），否则会引发检查错误；
• 自定义函数若需类似行为，务必在 typeshed 兼容 stub 文件或内联 @overload 中完整覆盖所有有意义的字面量组合，避免漏掉分支导致类型不安全。

通过这一模式，你既能保持代码运行时灵活性，又能让类型检查器提供媲美内置函数的精准推断能力。