python 类型检查器（如 pyright）可通过 `@overload` 结合 `literal` 类型，根据字符串参数的**编译期已知字面值**（如 `"r"` 或 `"rb"`）精确推断不同返回类型，而非仅依赖运行时变量——这是类型系统对“值敏感类型”的标准支持方式。
在 Python 类型提示中，TypeVar 适用于基于类型的泛型推导（例如 def first[T](lst: list[T]) -> T: ...），但无法表达“若参数值为 'rb'，则返回 BufferedReader；若为 'r'，则返回 TextIOWrapper”这类值驱动的类型分支。此时，标准且可移植的解决方案是使用 @overload 装饰器配合 Literal 类型。
Literal 表示一个或多个具体的、不可变的字面值（如 Literal['r', 'w']），它告诉类型检查器：该参数在调用点必须是这些值之一，且其具体取值可用于选择对应的重载签名。@overload 则允许为同一函数定义多个类型契约，检查器在调用时依据实参的静态可判定字面值匹配最精确的签名。
以下是一个完整、符合 PEP 484 和 typing 标准的示例：
from typing import overload, Literal, IO, Any
from io import TextIOWrapper, BufferedReader, BufferedWriter, BytesIO
# 定义模式字面量类型（更严谨可扩展）
TextModes = Literal['r', 'w', 'a', 'r+', 'w+', 'a+']
BinaryModes = Literal['rb', 'wb', 'ab', 'rb+', 'wb+', 'ab+']
@overload
def open_file(filename: str, mode: TextModes = 'r', encoding: str | None = ...) -> TextIOWrapper:
...
@overload
def open_file(filename: str, mode: BinaryModes, encoding: None = ...) -> BufferedReader | BufferedWriter:
...
@overload
def open_file(filename: str, mode: str, encoding: str | None = ...) -> IO[Any]:
...
def open_file(filename: str, mode: str = 'r', encoding: str | None = None) -> IO[Any]:
# 运行时逻辑（此处仅为示意，实际应调用内置 open）
if 'b' in mode:
return BufferedReader(BytesIO()) # 简化模拟
else:
return TextIOWrapper(BytesIO(), encoding=encoding or 'utf-8')✅ 关键要点说明：
- ✅ Literal 必须作用于编译期可确定的字面量：open_file("x.txt", "rb") 可精确匹配二进制重载；而 mode = "rb"; open_file("x.txt", mode) 中 mode 是 str 类型变量，丢失字面信息，回退到最宽泛的 IO[Any] 签名（这正是你观察到的 Pyright 行为）。
- ✅ @overload 声明不包含实现，仅提供类型契约；实际函数体需覆盖所有重载路径（通常通过宽松类型如 IO[Any] 实现）。
- ✅ Pyright 对内置 open 的精准推断并非硬编码，而是因其类型存根（builtins.pyi）中已正确定义了 @overload + Literal 组合——这是标准库维护者遵循 PEP 规范的成果，任何第三方函数均可依此模式实现。
⚠️ 注意事项：
- 避免过度使用 Literal 枚举（如穷举全部 20+ 模式组合），应按语义分组（如 TextModes / BinaryModes），兼顾可维护性与精度；
- 若需支持动态模式（如从配置读取），类型系统天然无法保证安全，应显式转换（如 cast(BufferedReader, open(...))）并辅以运行时校验；
- 所有重载签名必须在实现函数之前声明，且实现函数签名需兼容所有重载（通常用最宽泛类型）。
这种模式是现代 Python 类型工程的核心实践之一，它让类型检查器既能保持静态分析能力，又能逼近运行时行为的精确性。
