python - 何时在 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，而.IO[bytes]

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

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

标签： pythonpython-3.xtype-hinting

Answer 1

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

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

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

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