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 类型系统“渐进式精确化”的设计哲学：在不破坏动态特性的前提下，通过声明式提示赋予工具链强大的推理能力。
