Когда использовать подсказки типа IO [str] / IO [bytes] и TextIO / BinaryIO в типе Python?

Question

В документации говорится, что:

Generi c type IO[AnyStr] и его подклассы TextIO(IO[str]) и BinaryIO(IO[bytes]) представляют типы потоков ввода-вывода, такие как возвращаемые open().

- Python Документы: typing.IO

В документах не указано, когда следует использовать BinaryIO / TextIO по их аналогам IO[str] и IO[bytes].

Благодаря простой проверке источника * Typeshed Python при поиске BinaryIO и обнаружено только 30 совпадений . 109 совпадений для IO[bytes].

Я пытался переключиться на BinaryIO с IO[bytes] для лучшей совместимости с sphinx-autodo c -типами , но переключение прервало множество проверок типов, так как методы, такие как tempfile.NamedTemporaryFile, набираются как IO[bytes] вместо других.

С точки зрения дизайна, каковы правильные ситуации для использования каждого типа этих подсказок типа ввода-вывода

Answer 1

BinaryIO и TextIO непосредственно подкласс IO[bytes] и IO[str] соответственно, и добавить несколько дополнительных методов - подробности см. В определениях в типизированном .

Поэтому, если вам нужны эти дополнительные методы, используйте BinaryIO/TextIO. В противном случае, вероятно, лучше использовать IO[...] для максимальной гибкости. Например, если вы аннотируете метод как принимающий IO[str], конечному пользователю будет немного проще предоставить экземпляр этого объекта.

Несмотря на все это, классы ввода-вывода в целом в настоящее время это довольно грязно: они определяют множество методов, которые на самом деле нужны не всем функциям. Таким образом, сопровождающие типа на самом деле рассматривают возможность разбить класс IO на меньшие протоколы . Вы могли бы сделать то же самое, если вы так склонны. Этот подход в основном полезен, если вы хотите определить свои собственные IO-подобные классы, но не хотите обременить реализацию полного typing.IO[...] API - или если вы используете какой-то класс, который почти IO-подобен, но не совсем .

Несмотря на это, все три подхода - использование BinaryIO/TextIO, IO[...] или определение более компактных пользовательских протоколов - совершенно верны. Если расширение sphinx по какой-то причине не в состоянии обработать один конкретный подход, возможно, это ошибка на его конце.