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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Необработанный ввод-вывод

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

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

API необработанного потока подробно описан в документации RawIOBase.

Классы базового ввода/вывода

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()

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

flush()

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

isatty()

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

readable()

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

readline(size=-1, /)

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

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

readlines(hint=-1, /)

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

Значения hint, равные 0 или меньше, а также None, обрабатываются как отсутствие подсказки.

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

seek(offset, whence=SEEK_SET, /)

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

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

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

Введено в версии 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 операционной системы, и не пытаются инкапсулировать его в высокоуровневые примитивы (эта функциональность выполняется на более высоком уровне в буферизованных двоичных потоках и текстовых потоках, описанных позже на этой странице).

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

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 раньше). Но для интерактивных потоков в сыром формате будет выполнен максимум один вызов считывания в сыром формате, и короткий результат не подразумевает, что EOF близок.

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

read1(size=-1, /)

Считать и вернуть до 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)

Необработанный двоичный поток, представляющий файл на уровне ОС, содержащий данные байтов. Он наследует RawIOBase.

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

• строка символов или объект bytes, представляющий путь к файлу, который будет открыт. В этом случае closefd должен быть True (по умолчанию), иначе будет поднято исключение.
• целое число, представляющее номер существующего дескриптора файла на уровне ОС, к которому получившийся объект FileIO получит доступ. Когда объект FileIO закрыт, этот дескриптор также будет закрыт, если только 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: Файл теперь не наследуется.

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

mode

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

name

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

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

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

class io.BytesIO(initial_bytes=b'')

Бинарный поток, использующий буфер байтов в памяти. Он наследует 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=-1, /)

В 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=0, /)

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

read(size=-1, /)

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

read1(size=-1, /)

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

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

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

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

flush()

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

write(b, /)

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

BufferedRandom способен на всё, что могут BufferedReader или BufferedWriter. Кроме того, seek() и tell() гарантированно реализованы.

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

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

reader и writer — это объекты RawIOBase, которые соответственно читаемый и записываемый. Если buffer_size не указан, он по умолчанию равен 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, /)

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

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

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

Добавлен в версии 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 равно '', режим универсальных новых строк включен, но окончания строк возвращаются вызывающей стороне без перевода. Если newline имеет любое другое законное значение, строки ввода завершаются только указанной строкой, а окончание строки возвращается вызывающей стороне без перевода.
• При записи выходных данных в поток, если 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 и IOBase:

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 не указан.

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

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

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

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

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

Буфер текста удаляется при вызове метода close().

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

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

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

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() также.