何时在 Python 类型提示中使用 IO[str]/IO[bytes] 和 TextIO/BinaryIO？

Question

从文档中，它说：

通用类型IO[AnyStr]及其子类TextIO(IO[str])和BinaryIO(IO[bytes])表示 I/O 流的类型，例如open()返回的类型。

— Python 文档：typing.IO

文档没有指定何时使用BinaryIO / TextIO而不是IO[str]和IO[bytes] 。

通过对 Python Typeshed 源代码的简单检查，在搜索BinaryIO时只找到了30 个命中，而IO[bytes]找到了109 个命中。

我试图从IO[bytes]切换到BinaryIO以更好地与sphinx-autodoc-typehints兼容，但切换破坏了许多类型检查，因为像tempfile.NamedTemporaryFile这样的方法被输入为IO[bytes]而不是另一个。

从设计角度来说，使用这些 IO 类型提示的每种类型的正确情况是什么？

Answer 1

BinaryIO和TextIO直接子类化IO[bytes]和IO[str] ，并添加一些额外的方法——具体请参见typeshed中的定义。

因此，如果您需要这些额外的方法，请使用BinaryIO/TextIO 。 否则，最好使用IO[...]以获得最大的灵活性。 例如，如果您将方法注释为接受IO[str] ，则最终用户提供该对象的实例会更容易一些。

尽管说了这么多，但目前的 IO 类总体上还是有些混乱：它们定义了许多并非所有函数都实际需要的方法。 因此，类型化维护者实际上正在考虑将 IO 类分解为更小的 Protocols 。 如果您愿意，您也许可以这样做。 如果您想定义自己的类似 IO 的类，但又不想承担实现完整的typing.IO[...] API 的负担，或者您正在使用一些几乎是 IO 的类，则这种方法非常有用。喜欢，但不完全是。

BinaryIO/TextIO ，所有三种方法——使用BinaryIO/TextIO 、 IO[...]或定义更紧凑的自定义协议——都是完全有效的。 如果 sphinx 扩展由于某种原因似乎无法处理一种特定的方法，那可能是他们的一个错误。