Python存根文件中如何无需导入外部包使用类型注解？

针对存根文件（.pyi）不能引入外部依赖、无法使用try/except导入的限制，以下是几种当前可行的通用方案，用于给支持多类型输入的参数添加类型注解：

1. 定义通用Protocol（推荐） #

利用Python的typing.Protocol（Python 3.8+支持，存根文件可直接使用），抽象出所有兼容文件系统类的核心公共方法，无需导入具体依赖库。类型检查器会自动识别实现了这些方法的对象，不管它来自pyarrow还是fsspec。

示例代码：

from typing import Protocol, Optional

class FileSystemLike(Protocol):
    # 定义两个FileSystem类共有的核心方法，根据实际需求补充
    def open(self, path: str, mode: str = ...) -> object:
        ...
    def exists(self, path: str) -> bool:
        ...
    def mkdir(self, path: str, parents: bool = ..., exist_ok: bool = ...) -> None:
        ...

class ParquetFile:
    def __init__(self, source: str, filesystem: Optional[FileSystemLike] = None) -> None:
        ...

这种方式既保证了类型检查的严格性，又完全不依赖外部库，是最通用的解决方案。

2. 字符串字面量类型引用 #

PEP 484支持用字符串字面量作为类型注解，存根文件无需导入依赖库，类型检查器（如mypy、pyright）会自动解析字符串对应的全路径类型。

示例代码：

from typing import Optional, Union

class ParquetFile:
    def __init__(
        self,
        source: str,
        filesystem: Optional[Union["pyarrow.filesystem.FileSystem", "fsspec.AbstractFileSystem"]] = None
    ) -> None:
        ...

注意：如果项目未安装pyarrow或fsspec，类型检查器可能会发出"无法找到类型"的警告，但存根文件本身不会报错。这种方式适合需要明确标注具体类型，但不想定义协议的场景。

3. Any结合文档字符串补充说明 #

如果追求快速兼容，可使用typing.Any作为类型，同时在文档字符串中明确说明允许的具体类型，给开发者提供清晰提示。

示例代码：

from typing import Optional, Any

class ParquetFile:
    def __init__(
        self,
        source: str,
        filesystem: Optional[Any] = None,
    ) -> None:
        """
        Args:
            source: 数据源路径或对象
            filesystem: 可选文件系统对象，支持 pyarrow.filesystem.FileSystem、fsspec.AbstractFileSystem 或 None
        """
        ...

这种方式类型检查的严格性最弱，但实现成本最低，适合对类型校验要求不高的场景。

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