在 python 类型提示中，当函数参数可接受多种类型（如 str、bytes 或 pathlike）时，应使用 typing.union 或更简洁的 | 语法（python 3.10+）进行联合类型标注。

在 python 类型提示中，当函数参数可接受多种类型（如 str、bytes 或 pathlike）时，应使用 typing.union 或更简洁的 | 语法（python 3.10+）进行联合类型标注。

当设计一个兼容路径抽象的函数（例如封装 os.scandir）时，参数 path 需支持字符串路径（str）、字节路径（bytes）以及任意实现 os.PathLike 协议的对象（如 pathlib.Path）。根据 PEP 519，官方推荐使用联合类型明确表达这种多态性。

✅ 正确写法（兼容 Python 3.5+）：

import os
import typing

def scan(path: typing.Union[str, bytes, os.PathLike]) -> typing.Iterator[os.DirEntry]:
    return os.scandir(path)

✅ 更现代、更简洁的写法（Python 3.10+，推荐）：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

import os

def scan(path: str | bytes | os.PathLike) -> os.Iterator[os.DirEntry]:
    return os.scandir(path)

⚠️ 注意事项：

立即学习“Python免费学习笔记（深入）”；

• os.PathLike 是一个协议（Protocol），定义在 os 模块中，无需从 typing 导入；它表示任何实现了 __fspath__() 方法的对象；
• 若需严格类型检查（如使用 mypy），建议同时导入 from typing import Iterator 并显式标注返回类型为 Iterator[os.DirEntry]（而非仅 os.DirEntry）；
• 避免使用字符串字面量（如 "str | bytes"）或 Any——它们会削弱类型安全性与 IDE 支持；
• Union 在 Python 3.10+ 中已支持 | 运算符作为等价语法，语义完全一致，但 | 更简洁、可读性更强，且是 PEP 604 推荐的标准形式。

? 小结：多类型参数的本质是“或”关系，应优先选用 Union[T1, T2, T3]（旧版）或 T1 | T2 | T3（新版）；结合 os.PathLike 可让函数天然兼容 pathlib.Path、os.fspath() 友好对象及传统字符串路径，兼顾灵活性与类型严谨性。