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

Возвращает дескриптор базового файла (целое число) потока, если он существует. Если объект 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)

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

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

read(size=-1)

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

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

Реализация по умолчанию обращается к readall() и readinto().

readall()

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

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

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

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

read1([size])

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

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

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 закрывается, этот дескриптор также будет закрыт, если только 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 — это объект, подобный байтам, содержащий начальные данные.

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 для заданного записываемого потока raw. Если buffer_size не задан, по умолчанию используется DEFAULT_BUFFER_SIZE.

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

flush()

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

write(b)

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буферизованный интерфейс для потоков с произвольным доступом. Он наследует BufferedReader и BufferedWriter.

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

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

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

Объект буферизованного ввода-вывода, объединяющий два однонаправленных объекта RawIOBase — один для чтения, другой для записи — в единый двунаправленный конечный пункт. Он наследует 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, читает до конца потока (EOF).

readline(size=-1)

Прочитать до перевода строки или конца потока (EOF) и вернуть одну строку str. Если поток уже в состоянии EOF, возвращается пустая строка.

Если указано 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 — 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 не указан.

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

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

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

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

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

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

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

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

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

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

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

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

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