Протокол статической типизации модуля io в Python

Добавлено в Python 3.14.

В модуле io добавлены два новых протокола статической типизации, которые можно использовать для аннотирования функций и методов, работающих с потоками ввода/вывода:

• io.Reader[T] - протокол для чтения из файла или другого входного потока,
• io.Writer[T] - протокол для записи в файл или другой выходной поток.

Эти протоколы помечены декоратором @typing.runtime_checkable, что позволяет проверять типы во время выполнения с помощью isinstance().

io.Reader[T]:

Класс io.Reader представляет собой обобщённый протокол для чтения из файла или другого входного потока.

Параметр T обычно представляет тип данных, считываемых из потока - например, str или bytes. НО он может быть любым типом, который поддерживает операцию чтения.

Пример использования:

from io import Reader

def read_it(reader: Reader[str]):
    data = reader.read(11)
    assert isinstance(data, str)

Методы класса io.Reader[T]

read():
read(size, /):

Читает данные из потока.

• Если указан size (целое число), будет прочитано не более size элементов (байтов или символов).
• Возвращает данные типа T.

io.Writer[T]:

Класс io.Writer[T] представляет собой обобщённый протокол для записи в файл или другой выходной поток.

Параметр T указывает тип данных, которые могут быть записаны в поток - например, str или bytes. Также может быть любым подходящим типом.

Пример использования:

from io import Writer

def write_binary(writer: Writer[bytes]):
    writer.write(b"Hello world!\n")

Метод класса io.Writer[T]

write(data, /):

Записывает данные в поток.

• data — данные типа T.
• Возвращает количество записанных элементов (байтов или символов).

Подробности реализации

• Оба класса (Reader и Writer) являются протоколами.
• Они совместимы с проверкой типов на этапе выполнения благодаря декоратору @typing.runtime_checkable.
• Это позволяет использовать их как типы в аннотациях:

def process(stream: Reader[bytes]) -> None:
    ...