Python 3.8+如何使用Structural Typing实现文件名类型提示

早年Stack Overflow相关问题中，开发者一直在寻找能覆盖所有可传入open()函数的文件名参数的类型提示方案，当时用户@lxop提出该需求依赖结构化类型（Structural Typing）特性，而该特性在当时仅处于PEP 544提案阶段，未正式落地。Python 3.8版本正式引入基于Protocol的结构化类型支持后，该问题已经有了标准、严谨的实现方案。

核心原理 #

Python内置open()函数接收的文件名参数并不局限于str类型，还支持：

• bytes格式的路径
• 实现了__fspath__()方法的路径对象（比如pathlib.Path实例、自定义路径类）
  传统名义类型需要类显式继承某个父类才能被识别为对应类型，无法覆盖所有满足「可作为路径传入open」的对象；而结构化类型只检查对象是否满足对应的方法/属性约定，不需要显式继承，正好匹配该场景的需求。在结构化类型正式落地前，开发者要么只能将参数标注为str漏掉大量合法入参，要么被迫用Any放弃类型检查，这也是当年问题中提到的核心痛点。

具体实现 #

你不需要自己从头实现协议类，Python标准库os模块中提供的os.PathLike就是基于结构化类型协议定义的路径类型，配合联合类型即可覆盖所有合法文件名入参：

from typing import Union
from os import PathLike

# 定义覆盖所有合法文件名入参的类型别名
FileName = Union[str, bytes, PathLike[str], PathLike[bytes]]

使用示例 #

from pathlib import Path

def load_file_content(file_path: FileName) -> bytes:
    with open(file_path, "rb") as f:
        return f.read()

# 以下所有调用都可以通过类型检查
load_file_content("./test.txt")  # str路径
load_file_content(b"./test.txt") # bytes路径
load_file_content(Path("./test.txt")) # pathlib路径对象

class CustomPath:
    def __fspath__(self) -> str:
        return "./test.txt"
load_file_content(CustomPath()) # 自定义实现路径协议的对象，同样可通过检查

补充说明 #

• Python 3.10及以上版本可以用更简洁的联合类型写法，不需要导入Union：

  FileName = str | bytes | PathLike[str] | PathLike[bytes]
  

• 如果你的函数不需要支持bytes格式的路径（比如固定以文本模式打开文件、指定了编码参数），可以把类型简化为str | PathLike[str]，减少不必要的类型兼容。
• os.PathLike本身支持运行时类型检查，你可以直接用isinstance(obj, PathLike)判断一个对象是否实现了路径协议，不需要额外加装饰器。
• 不要用Any标注文件名类型，会完全丢失类型检查的约束；也不要只标注str，会导致传入pathlib.Path等合法路径对象时被类型检查器误报错误。

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