os.PathLike[Any]与os.PathLike[str]区别及传字符串mypy报错问题

1. os.PathLike[Any]与os.PathLike[str]的区别 #

os.PathLike本身在CPython运行时实现中不是泛型类型，泛型参数是类型标注体系为其补充的定义，仅在静态类型检查阶段生效，用于标识__fspath__方法的返回值类型：

• os.PathLike[str]：表示该类型实现的__fspath__方法返回字符串类型的路径，仅接收可导出字符串路径的PathLike实现类实例
• os.PathLike[Any]：不对__fspath__的返回值类型做限制，支持返回str或bytes的所有PathLike实现类，等价于不加泛型参数直接写os.PathLike

2. 报错成因 #

你遇到的报错核心原因是：字符串类型str本身没有实现os.PathLike接口，它没有定义__fspath__方法，不属于os.PathLike的子类。
当你把函数参数标注为os.PathLike[str]时，类型检查器只会允许传入PathLike的实现类实例（比如pathlib.Path的实例），此时传入字符串自然会触发类型不匹配的错误。

3. 正确的路径类型标注方案 #

根据你的实际需求可以选择不同的标注方式：

• 若需要兼容所有合法路径类型（字符串、bytes、Path对象等），可以标注为typing.Union[str, bytes, os.PathLike]，Python 3.10+可简化为str | bytes | os.PathLike
• 若只需要支持字符串和字符串类型的PathLike实例，标注为Union[str, os.PathLike[str]]即可，此时传入字符串不会触发类型错误，修正后的示例代码如下：

import os
import pathlib
from typing import Union

def test(f: Union[str, os.PathLike[str]]):
    print(pathlib.Path(f))

test(r"C:\Program Files")

• 若仅接收Path对象，直接标注为pathlib.Path即可
• 若不需要限制PathLike的返回值类型，直接使用os.PathLike不加泛型参数即可，等价于os.PathLike[Any]

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