为何io.BytesIO非typing.BinaryIO子类，io.StringIO非typing.TextIO子类？

在使用Python的match-case模式时，发现case typing.BinaryIO():无法匹配io.BytesIO类型的对象。通过以下测试代码验证了这一现象：

import io
import typing

assert issubclass(list, typing.Sequence)
assert issubclass(list, typing.List)
assert issubclass(dict, typing.Mapping)
assert issubclass(dict, typing.Dict)
# assert issubclass(io.StringIO, typing.TextIO) # 执行失败！
# assert issubclass(io.BytesIO, typing.BinaryIO) # 执行失败！

a = [1, 2, 3]
b = {"a": 1, "b": 2, "c": 3}
c = io.BytesIO(b"123123123")
d = io.StringIO("123123123")

assert isinstance(a, typing.List)
assert isinstance(a, typing.Sequence)
assert isinstance(b, typing.Dict)
assert isinstance(b, typing.Mapping)
# assert isinstance(c, typing.BinaryIO) # 执行失败！
# assert isinstance(d, typing.TextIO) # 执行失败！

测试结果显示，io.BytesIO并非typing.BinaryIO的子类，io.StringIO也不是typing.TextIO的子类，这和直觉不符。同时，在Pylance扩展的typeshed存根文件/data/users/XXXXXX/.vscode-server/extensions/ms-python.vscode-pylance-2024.11.1/dist/typeshed-fallback/stdlib/_io.pyi中，存在class BytesIO(BufferedIOBase, _BufferedIOBase, BinaryIO):这样的代码，暗示两者应该有继承关系。问题在于：这是Python的有意设计还是Bug？如果是设计，原因是什么？

环境：Python 3.12.3、mypy 1.13.0、VSCode 1.93.1、Pylance 2024.11.1扩展。

结论：这是有意设计 #

核心原因： #

• typing.BinaryIO/typing.TextIO是静态类型用的Protocol，而非运行时类
  Python的typing模块中，BinaryIO、TextIO本质是Protocol（协议类型），用来描述对象应该具备的行为（比如read、write、seek等IO操作方法），而非实际的类。这类协议默认没有运行时检查能力——Python的isinstance/issubclass只能识别运行时存在的类继承关系，无法识别基于鸭子类型的协议匹配。

• 存根文件的继承关系仅服务静态类型检查
  .pyi存根文件里标注的BytesIO继承BinaryIO，是给mypy、Pylance这类静态类型检查工具看的，目的是告诉检查器：BytesIO完全符合BinaryIO协议定义的行为规范，所以在静态代码检查时会认为两者类型兼容，但这一关系不会映射到Python运行时。

• 避免运行时性能开销
  如果要让Protocol支持运行时检查，需要给它加上@runtime_checkable装饰器，但Python官方没有给BinaryIO/TextIO加这个装饰器——因为这类协议需要检查对象是否具备多个方法，运行时检查会带来额外性能损耗，而Python类型提示的核心定位是服务静态代码检查，而非运行时类型验证。

解决方案： #

如果需要在match-case中匹配IO类型对象，直接使用实际类即可：

obj = io.BytesIO(b"test")
match obj:
    case io.BytesIO():
        print("匹配到BytesIO对象")
    case io.StringIO():
        print("匹配到StringIO对象")

如果一定要基于协议做运行时匹配，可以自定义一个带@runtime_checkable的Protocol：

import io
from typing import Protocol, runtime_checkable

@runtime_checkable
class MyBinaryIO(Protocol):
    def read(self, __n: int = ...) -> bytes: ...
    def write(self, __b: bytes) -> int: ...

obj = io.BytesIO(b"test")
assert isinstance(obj, MyBinaryIO)  # 此时断言会成功

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