如何满足mypy的SupportsWrite[str]类型合规要求

问题核心原因 #

1. _typeshed是mypy专属的类型桩模块，仅用于类型检查阶段，运行时不存在，直接在Python解释器导入必然报错。
2. 初始返回FileIO报错是因为FileIO是二进制IO类型，其write方法仅接受bytes类型参数，而print的file参数需要支持写入str的IO对象，类型不匹配。
3. 修改为Union[SupportsWrite[str], SupportsRead[str]]后依然报错，是因为该联合类型包含了仅支持读的分支，mypy无法判定你当前传入w+模式时返回的是可写类型，因此触发类型不兼容错误。

可行解决方案 #

方案1：直接使用公开的typing.IO类型（最简单） #

如果你的sopen返回的是文本模式的IO对象，直接用typing.TextIO作为返回值类型即可，该类型是Python typing模块公开的，运行时可正常导入，无需依赖_typeshed：

from typing import TextIO

def sopen(anything_at_all: str, mode: str) -> TextIO:
    ...

TextIO本身实现了SupportsWrite[str]接口，完全匹配print的file参数要求，mypy检查直接通过。

方案2：使用类型重载实现精确类型推断 #

如果需要根据不同mode参数返回不同的IO类型（比如只读、只写、二进制、文本），可以用typing.overload定义重载签名，mypy会自动根据传入的mode匹配对应返回类型：

from __future__ import annotations
from typing import overload, Literal, TYPE_CHECKING

if TYPE_CHECKING:
    from _typeshed import SupportsRead, SupportsWrite

# 只读文本模式重载
@overload
def sopen(anything_at_all: str, mode: Literal['r', 'rt']) -> SupportsRead[str]: ...

# 可写文本模式重载
@overload
def sopen(anything_at_all: str, mode: Literal['w', 'wt', 'w+', 'wt+', 'a', 'at']) -> SupportsWrite[str]: ...

# 实际函数定义
def sopen(anything_at_all: str, mode: str) -> object:
    # 原有实现逻辑
    ...

调用时传入mode='w+'会自动匹配可写重载，不会触发类型错误。

方案3：调用时强制类型转换 #

如果不想修改函数定义，可以在调用print时用typing.cast告知mypy当前对象的实际类型，该方法运行时无额外开销：

from __future__ import annotations
from typing import cast, TYPE_CHECKING

if TYPE_CHECKING:
    from _typeshed import SupportsWrite

def sopen(anything_at_all: str, mode: str):
    # 原有实现
    ...

with sopen('footxt.gz', mode = 'w+') as fout:
    print("hello, world!", file=cast(SupportsWrite[str], fout))

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