Python类型注解如何声明兼容os.PathLike与pathlib.Path的路径变量

TypeVar的设计目的是定义泛型场景下的类型占位符，它必须绑定在明确的泛型上下文中才能生效：要么作为泛型类的类型参数（继承Generic[YourTypeVar]时绑定），要么出现在函数签名的参数/返回值位置，用来标记「同一类型变量在多个位置的类型必须保持一致」的约束。
直接将PathLike这个TypeVar用于注解独立的模块级/局部变量时，类型检查器找不到它的绑定上下文，就会抛出「Type variable is unbound」的错误。
简单说，TypeVar是用来做类型一致性约束的，不是用来做「多类型枚举」的：你之前写的TypeVar("PathLike", str, Path)，适用场景是泛型约束——比如写一个函数，要求传入str类型路径就返回str结果，传入Path类型路径就返回Path结果，这时候把PathLike放在函数签名里才是正确用法。如果只是要标注一个变量可能是多种类型之一，应该用联合类型，而不是TypeVar。

所有可以直接传入open()的对象官方统称为path-like object，标准库已经提供了对应的类型定义，不需要自己用TypeVar实现：

• 最通用的写法是标注为str | os.PathLike[str]（Python 3.10+），或者Union[str, os.PathLike[str]]（Python 3.6~3.9）。其中os.PathLike是所有实现了__fspath__()方法的路径对象的抽象基类，pathlib.Path本身就实现了该接口，完全被这个类型覆盖，兼容所有os.path风格的字符串路径、pathlib路径对象，以及其他自定义的路径类对象。open()函数本身的类型签名就接受该类型参数，用它做注解不会触发类型不匹配错误。
• 如果需要在项目里复用这个类型，可以直接定义普通类型别名，不要用TypeVar：

# Python 3.10+
import os
from typing import TypeAlias
PathLike: TypeAlias = str | os.PathLike[str]

# Python 3.9及更早版本
import os
from typing import Union
PathLike = Union[str, os.PathLike[str]]

定义完成后直接用fpath: PathLike注解变量即可，不会触发未绑定错误。

• 如果你确实需要约束「类型只能是str或者Path，不接受其他自定义PathLike对象」，直接用联合类型注解即可，同样不需要TypeVar：

# Python 3.10+
from pathlib import Path
fpath: str | Path

# Python 3.9及更早版本
from typing import Union
from pathlib import Path
fpath: Union[str, Path]

修正后的可通过类型检查的代码示例：

from pathlib import Path
import os
from typing import Union # Python 3.10+版本可删除该行，将下方类型替换为 str | os.PathLike[str]
from some_module import some_function

fpath: Union[str, os.PathLike[str]]
line: str

fpath = some_function()
with open(fpath, "rt") as f:
    line = f.readline()

内容的提问来源于stack exchange，提问作者Dobedani