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 中完整覆盖所有有意义的字面量组合，避免漏掉分支导致类型不安全。
通过这一模式，你既能保持代码运行时灵活性，又能让类型检查器提供媲美内置函数的精准推断能力。
