何时在 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源的一个简单的检查，只有30命中发现搜索时BinaryIO，和109分的命中了IO[bytes]。

我试图切换到BinaryIOfromIO[bytes]以更好地与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，IO[...]或定义更紧凑的自定义协议-是完全有效的。如果 sphinx 扩展由于某种原因似乎无法处理一种特定的方法，那可能是他们的一个错误。