[英]When to use IO[str]/IO[bytes] and TextIO/BinaryIO in Python type hinting?
From the documentation, it says that:从文档中,它说:
Generic type
IO[AnyStr]
and its subclassesTextIO(IO[str])
andBinaryIO(IO[bytes])
represent the types of I/O streams such as returned byopen()
.通用类型
IO[AnyStr]
及其子类TextIO(IO[str])
和BinaryIO(IO[bytes])
表示 I/O 流的类型,例如open()
返回的类型。
The docs did not specify when BinaryIO
/ TextIO
shall be used over their counterparts IO[str]
and IO[bytes]
.文档没有指定何时使用
BinaryIO
/ TextIO
而不是IO[str]
和IO[bytes]
。
Through a simple inspection of the Python Typeshed source, only 30 hits found when searching for BinaryIO
, and 109 hits for IO[bytes]
.通过对 Python Typeshed 源代码的简单检查,在搜索
BinaryIO
时只找到了30 个命中,而IO[bytes]
找到了109 个命中。
I was trying to switch to BinaryIO
from IO[bytes]
for better compatibility with sphinx-autodoc-typehints , but the switch-over has broken many type checks as methods like tempfile.NamedTemporaryFile
is typed as IO[bytes]
instead of the other.我试图从
IO[bytes]
切换到BinaryIO
以更好地与sphinx-autodoc-typehints兼容,但切换破坏了许多类型检查,因为像tempfile.NamedTemporaryFile
这样的方法被输入为IO[bytes]
而不是另一个。
Design-wise speaking, what are the correct situations to use each type of these IO type hints?从设计角度来说,使用这些 IO 类型提示的每种类型的正确情况是什么?
BinaryIO
and TextIO
directly subclass IO[bytes]
and IO[str]
respectively, and add on a few extra methods -- see the definitions in typeshed for the specifics. BinaryIO
和TextIO
直接子类化IO[bytes]
和IO[str]
,并添加一些额外的方法——具体请参见typeshed中的定义。
So if you need these extra methods, use BinaryIO/TextIO
.因此,如果您需要这些额外的方法,请使用
BinaryIO/TextIO
。 Otherwise, it's probably best to use IO[...]
for maximum flexibility.否则,最好使用
IO[...]
以获得最大的灵活性。 For example, if you annotate a method as accepting an IO[str]
, it's a bit easier for the end-user to provide an instance of that object.例如,如果您将方法注释为接受
IO[str]
,则最终用户提供该对象的实例会更容易一些。
Though all this being said, the IO classes in general are kind of messy at present: they define a lot of methods that not all functions will actually need.尽管说了这么多,但目前的 IO 类总体上还是有些混乱:它们定义了许多并非所有函数都实际需要的方法。 So, the typeshed maintainers are actually considering breaking up the IO class into smaller Protocols .
因此,类型化维护者实际上正在考虑将 IO 类分解为更小的 Protocols 。 You could perhaps do the same, if you're so inclined.
如果您愿意,您也许可以这样做。 This approach is mostly useful if you want to define your own IO-like classes but don't want the burden of implementing the full
typing.IO[...]
API -- or if you're using some class that's almost IO-like, but not quite.如果您想定义自己的类似 IO 的类,但又不想承担实现完整的
typing.IO[...]
API 的负担,或者您正在使用一些几乎是 IO 的类,则这种方法非常有用。喜欢,但不完全是。
All this being said, all three approaches -- using BinaryIO/TextIO
, IO[...]
, or defining more compact custom Protocols -- are perfectly valid. BinaryIO/TextIO
,所有三种方法——使用BinaryIO/TextIO
、 IO[...]
或定义更紧凑的自定义协议——都是完全有效的。 If the sphinx extension doesn't seem to be able to handle one particular approach for some reason, that's probably a bug on their end.如果 sphinx 扩展由于某种原因似乎无法处理一种特定的方法,那可能是他们的一个错误。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.