io — Основные инструменты для работы с потоками

Исходный код: Lib/io.py

Обзор

Модуль io предоставляет основные возможности Python для работы с различными типами ввода-вывода. Существует три основных типа ввода-вывода: текстовый ввод-вывод, бинарный ввод-вывод и сырой ввод-вывод. Это общие категории, и для каждой из них могут использоваться различные хранилища. Конкретный объект, относящийся к любой из этих категорий, называется объектом файла. Другими распространёнными терминами являются поток и объект, подобный файлу.

Независимо от своей категории, каждый конкретный потоковый объект также будет обладать различными возможностями: он может быть только для чтения, только для записи или для чтения и записи. Он также может допускать произвольный случайный доступ (переход вперёд или назад к любому месту) или только последовательный доступ (например, в случае сокета или канала).

Все потоки тщательно проверяют тип данных, которые вы им передаёте. Например, передача объекта str методу write() бинарного потока вызовет исключение TypeError. То же произойдёт при передаче объекта bytes методу write() текстового потока.

Текстовый ввод-вывод

Текстовый ввод-вывод ожидает и производит объекты str. Это означает, что всякий раз, когда хранилище по своей природе состоит из байтов (например, в случае файла), кодирование и декодирование данных выполняется прозрачно, а также выполняется необязательное преобразование символов новой строки, специфичных для платформы.

Самый простой способ создать текстовый поток — с помощью open(), при необходимости указав кодировку:

f = open("myfile.txt", "r", encoding="utf-8")

В памяти текстовые потоки также доступны как объекты StringIO:

f = io.StringIO("some initial text data")

Интерфейс текстового потока подробно описан в документации TextIOBase.

Бинарный ввод-вывод

Бинарный ввод-вывод (также называемый буферизованным вводом-выводом) ожидает объекты типа байтов и производит объекты bytes. Никакое кодирование, декодирование или преобразование символов новой строки не выполняется. Эта категория потоков может быть использована для всех видов нетекстовых данных, а также когда требуется ручное управление обработкой текстовых данных.

Самый простой способ создать бинарный поток — с помощью open() с 'b' в строке режима:

f = open("myfile.jpg", "rb")

В памяти бинарные потоки также доступны как объекты BytesIO:

f = io.BytesIO(b"some initial binary data: \x00\x01")

Интерфейс бинарного потока подробно описан в документации BufferedIOBase.

Другие модули библиотек могут предоставлять дополнительные способы создания текстовых или бинарных потоков. Например, см. socket.socket.makefile().

Сырой ввод-вывод

Сырой ввод-вывод (также называемый небуферизованным вводом-выводом) обычно используется в качестве низкоуровневого строительного блока для бинарных и текстовых потоков; редко бывает полезно непосредственно манипулировать сырым потоком из кода пользователя. Тем не менее, вы можете создать сырой поток, открыв файл в бинарном режиме с отключенной буферизацией:

f = open("myfile.jpg", "rb", buffering=0)

Интерфейс сырого потока подробно описан в документации RawIOBase.

Интерфейс модуля высокого уровня

io.DEFAULT_BUFFER_SIZE

Целое число, содержащее размер буфера по умолчанию, используемый классами буферизованного ввода-вывода модуля. open() использует blksize файла (как получено из os.stat()), если это возможно.

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Это псевдоним для встроенной функции open().

exception io.BlockingIOError

Это совместимый псевдоним для встроенного исключения BlockingIOError.

exception io.UnsupportedOperation

Исключение, наследующее от OSError и ValueError, которое возникает при вызове недопустимой операции над потоком.

Потоки в памяти

Также можно использовать str или объект типа байтов в качестве файла для чтения и записи. Для строк можно использовать StringIO, как файл, открытый в текстовом режиме. BytesIO можно использовать как файл, открытый в бинарном режиме. Оба предоставляют полные возможности чтения и записи со случайным доступом.

Иерархия классов

Реализация потоков ввода-вывода организована в виде иерархии классов. Сначала абстрактные базовые классы (ABC), которые используются для определения различных категорий потоков, затем конкретные классы, предоставляющие стандартные реализации потоков.

В верхней части иерархии ввода-вывода находится абстрактный базовый класс IOBase. Он определяет базовый интерфейс потока. Обратите внимание, однако, что разделения между чтением и записью в потоки нет; реализациям разрешается вызывать UnsupportedOperation, если они не поддерживают данную операцию.

Класс RawIOBase ABC расширяет IOBase. Он обрабатывает чтение и запись байтов в поток. FileIO наследуется от RawIOBase, чтобы предоставить интерфейс к файлам в файловой системе компьютера.

Класс BufferedIOBase ABC обрабатывает буферизацию в сыром потоке байтов (RawIOBase). Его подклассы, BufferedWriter, BufferedReader и BufferedRWPair, буферизуют потоки, которые могут быть читаемыми, записываемыми и читаемыми и записываемыми одновременно. BufferedRandom обеспечивает буферизованный интерфейс к потокам с произвольным доступом. Ещё один подкласс BufferedIOBase, BytesIO, представляет собой поток байтов в памяти.

Абстрактный базовый класс TextIOBase, являющийся подклассом IOBase, обрабатывает потоки, байты которых представляют текст, и осуществляет кодирование и декодирование в строки и из строк. TextIOWrapper, расширяющий его, представляет собой буферизованный текстовый интерфейс к буферизованному потоку данных (BufferedIOBase). Наконец, StringIO — это поток в памяти для работы с текстом.

Имена аргументов не являются частью спецификации, и только аргументы функции open() предназначены для использования в качестве ключевых аргументов.

В следующей таблице представлен сводный обзор ABC, предоставляемых модулем io:

Классы базовых операций ввода-вывода

class io.IOBase

Абстрактный базовый класс для всех классов ввода-вывода, работающих с потоками байтов. Публичный конструктор отсутствует.

Этот класс предоставляет пустые абстрактные реализации многих методов, которые производные классы могут выборочно переопределять; по умолчанию реализации представляют собой файл, который нельзя читать, писать или позиционировать.

Несмотря на то, что IOBase не объявляет read() или write(), так как их сигнатуры будут различаться, реализации и клиенты должны рассматривать эти методы как часть интерфейса. Кроме того, реализации могут генерировать исключение ValueError (или UnsupportedOperation) при вызове операций, которые они не поддерживают.

Основной тип, используемый для двоичных данных, считываемых или записываемых в файл, — bytes. В качестве аргументов методов также принимаются и другие объекты, подобные байтам. Классы текстового ввода-вывода работают с данными str.

Обратите внимание, что вызов любого метода (даже запроса) для закрытого потока является неопределённым. Реализации могут генерировать ValueError в этом случае.

IOBase (и его подклассы) поддерживает протокол итератора, что означает, что объект IOBase может быть перебираем, возвращая строки из потока. Строки определяются несколько по-разному в зависимости от того, является ли поток двоичным потоком (возвращая байты) или текстовым потоком (возвращая строки символов). См. readline() ниже.

IOBase также является менеджером контекста и поэтому поддерживает оператор with. В этом примере file закрывается после завершения блока оператора with, даже если произойдёт исключение:

with open('spam.txt', 'w') as file:
    file.write('Spam and eggs!')

IOBase предоставляет следующие атрибуты и методы:

close()

Очистить и закрыть этот поток. Этот метод не имеет эффекта, если файл уже закрыт. После закрытия файла любая операция с файлом (например, чтение или запись) вызовет ValueError.

Для удобства допускается вызывать этот метод более одного раза; однако, только первый вызов будет иметь эффект.

closed

True если поток закрыт.

fileno()

Возвращает дескриптор файла (целое число) базового потока, если он существует. Если объект IO не использует дескриптор файла, возникает OSError.

flush()

Очистить буферы записи потока, если применимо. Для потоков чтения только для чтения и неблокирующих потоков это ничего не делает.

isatty()

Возвращает True, если поток интерактивен (т.е. подключён к терминалу/устройству tty).

readable()

Возвращает True, если к потоку можно осуществить чтение. Если False, read() вызовет OSError.

readline(size=-1)

Прочитать и вернуть одну строку из потока. Если указан size, будет прочитано не более size байтов.

Разделитель строки всегда b'\n' для двоичных файлов; для текстовых файлов аргумент newline к open() может быть использован для выбора разделителя(ей) строк, распознаваемых.

readlines(hint=-1)

Прочитать и вернуть список строк из потока. hint может быть указан для управления количеством считываемых строк: больше строк не будет прочитано, если общий размер (в байтах/символах) всех строк до сих пор превышает hint.

Обратите внимание, что уже возможно итерировать по объектам файлов, используя for line in file: ..., без вызова file.readlines().

seek(offset, whence=SEEK_SET)

Изменить позицию потока на заданный байтовый смещение. смещение интерпретируется относительно позиции, указанной whence. Значение по умолчанию для whence равно SEEK_SET. Значения whence:

• SEEK_SET или 0 — начало потока (по умолчанию); смещение должно быть равно нулю или положительному
• SEEK_CUR или 1 — текущая позиция потока; смещение может быть отрицательным
• SEEK_END или 2 — конец потока; смещение обычно отрицательное

Возвращает новую абсолютную позицию.

Добавлена в версии 3.1: Константы SEEK_*.

Добавлена в версии 3.3: Некоторые операционные системы могут поддерживать дополнительные значения, такие как os.SEEK_HOLE или os.SEEK_DATA . Допустимые значения для файла могут зависеть от того, открыт ли он в текстовом или двоичном режиме.

seekable()

Возвращает True, если поток поддерживает произвольный доступ. Если False, seek(), tell() и truncate() вызовут OSError.

tell()

Возвращает текущую позицию потока.

truncate(size=None)

Изменить размер потока на заданный size в байтах (или текущую позицию, если size не указан). Текущая позиция потока не изменяется. Это изменение размера может расширить или уменьшить текущий размер файла. В случае расширения содержимое новой области файла зависит от платформы (на большинстве систем дополнительные байты заполняются нулями). Возвращается новый размер файла.

Изменено в версии 3.5: Windows теперь заполняет файлы нулями при расширении.

writable()

Возвращает True, если поток поддерживает запись. Если False, write() и truncate() вызовут OSError.

writelines(lines)

Записать список строк в поток. Разделители строк не добавляются, поэтому обычно каждая предоставленная строка имеет разделитель строк в конце.

__del__()

Подготовиться к уничтожению объекта. IOBase предоставляет реализацию этого метода по умолчанию, которая вызывает метод close() экземпляра.

class io.RawIOBase

Базовый класс для операций ввода-вывода ссылочных бинарных данных. Он наследуется от IOBase. Публичного конструктора нет.

Ввод-вывод ссылочных бинарных данных, как правило, предоставляет низкоуровневый доступ к базовому устройству или API операционной системы, не пытаясь инкапсулировать его в высокоуровневые примитивы (это оставлено для буферизованного ввода-вывода и текстового ввода-вывода, описанных позже на этой странице).

В дополнение к атрибутам и методам из IOBase, RawIOBase предоставляет следующие методы:

read(size=-1)

Считать до size байтов из объекта и вернуть их. Для удобства, если size не указано или равно -1, возвращаются все байты до конца файла. В противном случае выполняется только один системный вызов. Может быть возвращено меньше, чем size байтов, если системный вызов вернул меньше, чем size байтов.

Если возвращено 0 байтов, а size не было равно 0, это указывает на конец файла. Если объект находится в режиме без ожидания и доступные байты отсутствуют, возвращается None.

Реализация по умолчанию делегирует вызов readall() и readinto().

readall()

Считать и вернуть все байты из потока до конца файла, используя несколько вызовов потока при необходимости.

readinto(b)

Считать байты в предварительно выделенный, доступный для записи объект-подобный байтам b и вернуть количество считанных байтов. Например, b может быть bytearray. Если объект находится в режиме без ожидания и доступные байты отсутствуют, возвращается None.

write(b)

Записать данный объект-подобный байтам, b, в базовый поток ссылочных данных и вернуть количество записанных байтов. Это может быть меньше длины b в байтах, в зависимости от особенностей базового потока ссылочных данных, особенно если он находится в режиме без ожидания. None возвращается, если базовый поток ссылочных данных настроен на работу без ожидания, и ни один байт не может быть немедленно записан в него. Вызывающая сторона может освободить или изменить b после возвращения этого метода, поэтому реализация должна обращаться к b только во время вызова метода.

class io.BufferedIOBase

Базовый класс для двоичных потоков, поддерживающих какой-либо вид буферизации. Он наследуется от IOBase. Публичного конструктора нет.

Основное отличие от RawIOBase состоит в том, что методы read(), readinto() и write() будут пытаться (соответственно) прочитать как можно больше входных данных, запрошенных пользователем, или обработать все предоставленные выходные данные, потенциально сделав при этом более одного системного вызова.

Кроме того, эти методы могут вызывать исключение BlockingIOError, если основной поток неблокирующего типа не может принять или передать достаточно данных; в отличие от своих аналогов в RawIOBase, они никогда не вернут None.

Кроме того, метод read() не имеет реализации по умолчанию, которая бы ссылалась на readinto().

Типичная реализация BufferedIOBase не должна наследоваться от реализации RawIOBase, а должна её обернуть, как это делают BufferedWriter и BufferedReader.

BufferedIOBase предоставляет или переопределяет эти методы и атрибуты в дополнение к тем, которые присутствуют в IOBase:

raw

Основной поток неблокирующего типа (экземпляр RawIOBase), с которым работает BufferedIOBase. Это не входит в API BufferedIOBase и может отсутствовать в некоторых реализациях.

detach()

Отделить основной поток неблокирующего типа от буфера и вернуть его.

После отделения основного потока неблокирующего типа буфер становится непригодным для использования.

Некоторые буферы, такие как BytesIO, не имеют концепции возвращаемого единственного основного потока из этого метода. Вместо этого они вызывают исключение UnsupportedOperation.

Введено в версии 3.1.

read(size=-1)

Прочитать и вернуть до size байт. Если аргумент опущен, None, или отрицателен, данные считываются и возвращаются до достижения конца потока (EOF). Если поток уже находится в конце потока, возвращается пустой объект bytes.

Если аргумент положителен, а основной поток не интерактивный, для удовлетворения количества байт могут быть выполнены несколько операций чтения из основного потока (если не будет достигнут конец потока (EOF)). Но для интерактивных потоков неблокирующего типа будет выполнена не более одна операция чтения, и короткий результат не подразумевает, что конец потока (EOF) близок.

Исключение BlockingIOError генерируется, если основной поток неблокирующего типа в неблокирующем режиме и в данный момент нет доступных данных.

read1([size])

Прочитать и вернуть до size байт, выполнив не более одного вызова метода read() (или readinto()) основного потока неблокирующего типа. Это может быть полезно, если вы реализуете собственную буферизацию на основе объекта BufferedIOBase.

Если size равно -1 (значение по умолчанию), возвращается произвольное количество байт (больше нуля, если не достигнут конец потока (EOF)).

readinto(b)

Прочитать байты в предварительно выделенный, записываемый объект типа байты b и вернуть количество прочитанных байт. Например, b может быть bytearray.

Как и read(), для получения данных из основного потока неблокирующего типа могут быть выполнены несколько операций чтения, если только он не является интерактивным.

Исключение BlockingIOError генерируется, если основной поток неблокирующего типа в неблокирующем режиме и в данный момент нет доступных данных.

readinto1(b)

Прочитать байты в предварительно выделенный, записываемый объект типа байты b, используя не более одного вызова метода read() (или readinto()) основного потока неблокирующего типа. Вернуть количество прочитанных байт.

Исключение BlockingIOError генерируется, если основной поток неблокирующего типа в неблокирующем режиме и в данный момент нет доступных данных.

Введено в версии 3.5.

write(b)

Записать данный объект типа байты, b, и вернуть количество записанных байт (всегда равное длине b, так как при неудачной записи будет вызвано исключение OSError). В зависимости от фактической реализации, эти байты могут быть немедленно записаны в основной поток или сохранены в буфере по соображениям производительности и задержки.

В неблокирующем режиме исключение BlockingIOError генерируется, если данные необходимо записать в основной поток неблокирующего типа, но он не может принять все данные без блокировки.

Вызывающая сторона может освободить или изменить b после возврата метода, поэтому реализация должна обращаться к b только во время вызова метода.

Неблокирующие потоки ввода-вывода файлов

class io.FileIO(name, mode='r', closefd=True, opener=None)

FileIO представляет собой файл на уровне операционной системы, содержащий данные в байтах. Он реализует интерфейс RawIOBase (и, следовательно, интерфейс IOBase тоже).

Имя может быть одним из двух:

• строка символов или объект bytes, представляющий путь к файлу, который будет открыт. В этом случае closefd должен быть True (по умолчанию), иначе произойдёт ошибка.
• целое число, представляющее номер существующего файла на уровне операционной системы, к которому получившийся объект FileIO получит доступ. Когда объект FileIO закрывается, этот дескриптор fd также будет закрыт, если только closefd не установлен в False.

Режим может быть 'r', 'w', 'x' или 'a' для чтения (по умолчанию), записи, эксклюзивного создания или добавления. Файл будет создан, если он не существует при открытии для записи или добавления; он будет усечён при открытии для записи. FileExistsError будет поднят, если он уже существует при открытии для создания. Открытие файла для создания подразумевает запись, поэтому этот режим работает аналогично 'w'. Добавьте '+' в режим, чтобы разрешить одновременное чтение и запись.

Методы read() (когда вызывается с положительным аргументом), readinto() и write() в этом классе будут выполнять только один системный вызов.

Пользовательский открыватель может быть использован путём передачи вызываемого объекта как opener. Тогда дескриптор файла для объекта файла получается путём вызова opener с (name, flags). opener должен возвращать открытый дескриптор файла (передача os.open как opener приводит к функциональности, аналогичной передаче None).

Созданный файл не может быть унаследован.

См. встроенную функцию open() для примеров использования параметра opener.

Изменено в версии 3.3: Параметр opener был добавлен. Режим 'x' был добавлен.

Изменено в версии 3.4: Файл теперь не может быть унаследован.

В дополнение к атрибутам и методам из IOBase и RawIOBase, FileIO предоставляет следующие данные атрибуты:

mode

Режим, заданный в конструкторе.

name

Имя файла. Это дескриптор файла, когда имя не указано в конструкторе.

Буферизованные потоки

Буферизованные потоки ввода-вывода предоставляют более высокий уровень доступа к устройству ввода-вывода, чем прямой доступ.

class io.BytesIO([initial_bytes])

Реализация потока, использующая буфер байтов в памяти. Он наследует BufferedIOBase. Буфер удаляется при вызове метода close().

Необязательный аргумент initial_bytes — это объект типа bytes, содержащий начальные данные.

BytesIO предоставляет или переопределяет следующие методы в дополнение к методам из BufferedIOBase и IOBase:

getbuffer()

Возвращает доступ к содержимому буфера для чтения и записи без копирования. Кроме того, изменение представления будет прозрачно обновлять содержимое буфера:

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

Примечание

Пока существует представление, объект BytesIO не может быть изменён в размерах или закрыт.

Новое в версии 3.2.

getvalue()

Возвращает bytes, содержащий всё содержимое буфера.

read1([size])

В BytesIO это то же самое, что и read().

Изменено в версии 3.7: Аргумент size теперь необязателен.

readinto1(b)

В BytesIO это то же самое, что и readinto().

Новое в версии 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буфер, предоставляющий более высокий уровень доступа к читаемому, последовательному объекту RawIOBase. Он наследует BufferedIOBase. При чтении данных из этого объекта может быть запрошено большее количество данных из базового потока, и оно будет сохранено во внутреннем буфере. Буферизованные данные затем могут быть возвращены непосредственно при последующих операциях чтения.

Конструктор создаёт BufferedReader для заданного читаемого потока raw и buffer_size. Если buffer_size не указан, используется DEFAULT_BUFFER_SIZE.

BufferedReader предоставляет или переопределяет следующие методы в дополнение к методам из BufferedIOBase и IOBase:

peek([size])

Возвращает байты из потока без продвижения позиции. Для выполнения вызова выполняется не более одного отдельного чтения из базового потока. Количество возвращённых байтов может быть меньше или больше, чем запрошенное.

read([size])

Считывает и возвращает size байт, или, если size не указан или отрицательный, до конца файла или если вызов чтения заблокируется в режиме без блокировки.

read1([size])

Считывает и возвращает до size байтов с использованием только одного вызова базового потока. Если хотя бы один байт находится в буфере, возвращаются только буферизованные байты. В противном случае выполняется один вызов чтения из базового потока.

Изменено в версии 3.7: Аргумент size теперь необязателен.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буфер, обеспечивающий доступ на более высоком уровне к записываемому, последовательному объекту RawIOBase. Он наследует BufferedIOBase. При записи в этот объект данные обычно помещаются во внутренний буфер. Буфер будет записан в базовый объект RawIOBase в различных условиях, включая:

• когда буфер становится слишком мал для всех ожидающих данных;
• когда вызывается flush();
• когда запрос на seek() (для объектов BufferedRandom);
• когда объект BufferedWriter закрывается или уничтожается.

Конструктор создаёт объект BufferedWriter для указанного записываемого сырого потока. Если размер_буфера не указан, он устанавливается по умолчанию в DEFAULT_BUFFER_SIZE.

BufferedWriter предоставляет или переопределяет эти методы в дополнение к методам BufferedIOBase и IOBase:

flush()

Принудительно помещает байты, содержащиеся в буфере, в сырой поток. BlockingIOError должен быть поднят, если сырой поток блокируется.

write(b)

Записать байтовый объект, b, и вернуть количество записанных байтов. В режиме без блокировки BlockingIOError поднимается, если буфер нужно записать, но сырой поток блокируется.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буферизованный интерфейс для потоков с произвольным доступом. Он наследует BufferedReader и BufferedWriter, и дополнительно поддерживает seek() и tell() функциональность.

Конструктор создаёт читатель и писатель для потока с возможностью перехода к определённой позиции (seekable), указанного в первом аргументе. Если размер_буфера не указан, он устанавливается по умолчанию в DEFAULT_BUFFER_SIZE.

BufferedRandom способен на всё, что может делать BufferedReader или BufferedWriter.

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)

Буферизованный объект ввода-вывода, объединяющий два однонаправленных объекта RawIOBase – один для чтения, другой для записи – в единый двунаправленный конечный пункт. Он наследует BufferedIOBase.

reader и writer – это объекты RawIOBase, которые соответственно предназначены для чтения и записи. Если размер_буфера не указан, он устанавливается по умолчанию в DEFAULT_BUFFER_SIZE.

BufferedRWPair реализует все методы BufferedIOBase, кроме detach(), который вызывает UnsupportedOperation.

Предупреждение

BufferedRWPair не пытается синхронизировать доступ к его базовым потокам. Вам не следует передавать ему один и тот же объект в качестве читателя и писателя; используйте BufferedRandom вместо этого.

Текстовый ввод-вывод

class io.TextIOBase

Базовый класс для текстовых потоков. Этот класс предоставляет интерфейс на основе символов и строк для потокового ввода-вывода. Он наследует IOBase. Нет публичного конструктора.

TextIOBase предоставляет или переопределяет эти атрибуты данных и методы в дополнение к методам IOBase:

encoding

Имя кодировки, используемой для декодирования байтов потока в строки и для кодирования строк в байты.

errors

Настройки обработки ошибок декодера или кодировщика.

newlines

Строка, кортеж строк или None, указывающие на переводы строк, переведённые до настоящего момента. В зависимости от реализации и флагов конструктора, это может быть недоступно.

buffer

Базовый двоичный буфер (экземпляр BufferedIOBase), с которым работает TextIOBase. Это не часть API TextIOBase и может отсутствовать в некоторых реализациях.

detach()

Отделить базовый двоичный буфер от TextIOBase и вернуть его.

После отделения базового буфера TextIOBase становится непригодным для использования.

Некоторые реализации TextIOBase, такие как StringIO, могут не иметь понятия о базовом буфере, и вызов этого метода вызовет UnsupportedOperation.

Добавлен в версии 3.1.

read(size=-1)

Прочитать и вернуть не более size символов из потока как единственную строку str. Если size отрицательно или None, считывает до конца файла.

readline(size=-1)

Прочитать до символа новой строки или конца файла и вернуть одну строку str. Если поток уже находится в состоянии конца файла, возвращается пустая строка.

Если указан size, будет прочитано не более size символов.

seek(offset, whence=SEEK_SET)

Изменить позицию потока на заданное смещение. Поведение зависит от параметра whence. Значение по умолчанию для whence – SEEK_SET.

• SEEK_SET или 0: перейти к позиции с начала потока (по умолчанию); смещение должно быть числом, возвращённым функцией TextIOBase.tell(), или нулём. Любое другое значение смещения приводит к неопределённому поведению.
• SEEK_CUR или 1: перейти к текущей позиции; смещение должно быть нулём, что является бездействующей операцией (все другие значения не поддерживаются).
• SEEK_END или 2: перейти к концу потока; смещение должно быть нулём (все другие значения не поддерживаются).

Возвращает новую абсолютную позицию как числовое значение.

Добавлен в версии 3.1: Постоянные значения SEEK_*.

tell()

Возвращает текущую позицию потока как числовое значение. Число обычно не представляет количество байтов в базовом двоичном хранилище.

write(s)

Записать строку s в поток и вернуть количество записанных символов.

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)

Буферизованный текстовый поток над двоичным потоком BufferedIOBase. Он наследует от TextIOBase.

encoding задаёт имя кодировки, используемой для декодирования или кодирования потока. По умолчанию используется locale.getpreferredencoding(False).

errors — необязательная строка, определяющая способ обработки ошибок кодирования и декодирования. Передача 'strict' вызовет исключение ValueError при ошибке кодирования (по умолчанию None имеет тот же эффект), или передача 'ignore' игнорирует ошибки. (Обратите внимание, что игнорирование ошибок кодирования может привести к потере данных.) 'replace' вставляет маркер замены (например, '?') при некорректных данных. 'backslashreplace' заменяет некорректные данные на обрамлённую обратной косой чертой последовательность. При записи 'xmlcharrefreplace' (замените соответствующей ссылкой на XML-символ) или 'namereplace' (замените на \N{...} последовательности экранирования) могут быть использованы. Любое другое имя обработки ошибок, зарегистрированное в codecs.register_error(), также допустимо.

newline управляет обработкой символов конца строки. Он может принимать значения None, '', '\n', '\r', и '\r\n'. Он работает следующим образом:

• При чтении данных из потока, если newline равен None, режим «универсальные символы новой строки» включён. Строки ввода могут завершаться '\n', '\r', или '\r\n', и эти символы переводятся в '\n' перед возвратом вызывающей стороне. Если это '', режим «универсальные символы новой строки» включён, но символы конца строки возвращаются вызывающей стороне без перевода. Если установлено любое другое допустимое значение, строки ввода завершаются только указанной строкой, и символ конца строки возвращается вызывающей стороне без перевода.
• При записи данных в поток, если newline равен None, все символы '\n' переводятся в системный разделитель строк os.linesep. Если newline равен '' или '\n', перевод не происходит. Если newline имеет любое другое допустимое значение, все символы '\n' переводятся в указанную строку.

Если line_buffering равен True, подразумевается flush() при вызове write, содержащем символ новой строки или возврата каретки.

Если write_through равен True, вызовы write() гарантированно не буферизируются: любые данные, записанные в объект TextIOWrapper, сразу обрабатываются его двоичным подлежащим buffer.

Изменено в версии 3.3: Аргумент write_through добавлен.

Изменено в версии 3.3: Значение по умолчанию encoding теперь равно locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Не изменяйте временную кодировку локали с помощью locale.setlocale(), используйте текущую кодировку локали вместо предпочтительной кодировки пользователя.

TextIOWrapper предоставляет следующие члены дополнительно к тем, что у TextIOBase и его предков:

line_buffering

Включена ли буферизация по строкам.

write_through

Передаются ли записи непосредственно в базовый двоичный буфер.

Введено в версии 3.7.

reconfigure(*[, encoding][, errors][, newline][, line_buffering][, write_through])

Перенастроить этот текстовый поток с новыми параметрами для encoding, errors, newline, line_buffering и write_through.

Неуказанные параметры сохраняют текущие значения, за исключением случая, когда errors='strict' используется при указании encoding, но не errors.

Изменение кодировки или newline невозможно, если из потока уже были прочитаны данные. С другой стороны, изменение кодировки после записи возможно.

Этот метод выполняет неявную очистку потока перед установкой новых параметров.

Введено в версии 3.7.

class io.StringIO(initial_value='', newline='\n')

Встроенный поток для текстового ввода-вывода. Текстовый буфер удаляется при вызове метода close().

Начальное значение буфера можно задать, указав initial_value. Если перевод новой строки включён, новые строки будут закодированы как при вызове write(). Поток устанавливается в начало буфера.

Аргумент newline работает аналогично TextIOWrapper. По умолчанию учитываются только символы \n как символы конца строки и перевод новых строк не производится. Если newline установлен в None, новые строки записываются как \n на всех платформах, но универсальное декодирование новых строк всё ещё выполняется при чтении.

StringIO предоставляет этот метод дополнительно к методам TextIOBase и его предков:

getvalue()

Возвращает str, содержащий всё содержимое буфера. Новые строки декодируются как при вызове read(), хотя положение потока не изменяется.

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

import io

output = io.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()

class io.IncrementalNewlineDecoder

Вспомогательный кодек, декодирующий символы новой строки для режима «универсальные символы новой строки». Он наследует от codecs.IncrementalDecoder.

Производительность

Этот раздел описывает производительность предоставленных конкретных реализаций ввода-вывода.

Двоичный ввод-вывод

Читая и записывая только большие блоки данных, даже когда пользователь запрашивает один байт, буферизованный ввод-вывод скрывает любую неэффективность в вызове и выполнении системных функций небуферизованного ввода-вывода. Выигрыш зависит от ОС и типа выполняемого ввода-вывода. Например, на некоторых современных ОС, таких как Linux, небуферизованный ввод-вывод на диск может быть таким же быстрым, как и буферизованный ввод-вывод. Однако, в конечном счёте, буферизованный ввод-вывод обеспечивает предсказуемую производительность независимо от платформы и устройства хранения. Поэтому почти всегда предпочтительнее использовать буферизованный ввод-вывод вместо небуферизованного ввода-вывода для двоичных данных.

Текстовый ввод-вывод

Текстовый ввод-вывод над двоичным хранилищем (таким как файл) значительно медленнее, чем двоичный ввод-вывод над тем же хранилищем, поскольку он требует преобразований между данными Юникод и двоичными данными с использованием кодека символов. Это может стать заметным при обработке огромных объёмов текстовых данных, таких как большие файлы журналов. Также TextIOWrapper.tell() и TextIOWrapper.seek() довольно медленны из-за используемого алгоритма реконструкции.

StringIO, однако, является встроенным контейнером Юникод в памяти и будет демонстрировать скорость, подобную BytesIO.

Многопоточность

FileIO объекты являются потокобезопасными в той мере, в какой системные вызовы (например, read(2) под Unix), которые они оборачивают, являются потокобезопасными.

Двоичные буферизованные объекты (экземпляры BufferedReader, BufferedWriter, BufferedRandom и BufferedRWPair) защищают свои внутренние структуры с помощью блокировки; поэтому безопасно вызывать их из нескольких потоков одновременно.

TextIOWrapper объекты не являются потокобезопасными.

Реентерабельность

Двоичные буферизованные объекты (экземпляры BufferedReader, BufferedWriter, BufferedRandom и BufferedRWPair) не являются реентерабельными. Хотя реентерабельные вызовы не происходят в обычных ситуациях, они могут возникнуть при выполнении ввода-вывода в обработчике signal. Если поток пытается повторно войти в буферизованный объект, к которому он уже имеет доступ, возникает исключение RuntimeError. Обратите внимание, это не запрещает другому потоку войти в буферизованный объект.

Вышеизложенное неявно распространяется на текстовые файлы, так как функция open() будет обертывать буферизованный объект внутри TextIOWrapper. Это включает стандартные потоки и, следовательно, влияет на встроенную функцию print() также.