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

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

16.2.1. Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Двоичные потоки в памяти также доступны в виде объектов BytesIO:

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

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

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

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

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

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

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

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

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, которое возникает при вызове недопустимой операции над потоком.

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

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

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

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

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

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

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

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

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

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

16.2.3.1. Классы базовых объектов ввода/вывода

class io.IOBase

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

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

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

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

Изменить позицию потока на заданное значение смещения 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, возвращаются все байты до конца файла. В противном случае выполняется только один системный вызов. Может быть возвращено меньше байтов, чем size, если вызов операционной системы возвращает меньше байтов, чем size.

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

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

readall()

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

readinto(b)

Прочитать байты в предварительно выделенный, записываемый объект-подобный байтам b и вернуть количество прочитанных байтов. Если объект находится в режиме «без блокировки» и байты недоступны, возвращается 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=-1)

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

readinto(b)

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

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

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

readinto1(b)

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

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

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

write(b)

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

В режиме «без блокировки» возникает BlockingIOError, если данные должны быть записаны в сырой поток, но он не может принять все данные без блокировки.

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

16.2.3.2. Сырой ввод-вывод файлов

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

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

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

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

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

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

readinto1()

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

read1(size)

Читает и возвращает до 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)

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

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

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

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 не пытается синхронизировать доступ к его базовым потокам. Не следует передавать ему один и тот же объект в качестве reader и writer; используйте BufferedRandom вместо этого.

16.2.3.4. Ввод-вывод текста

class io.TextIOBase

Базовый класс для текстовых потоков. Этот класс предоставляет интерфейс на основе символов и строк для ввода-вывода потоков. Метод readinto() отсутствует, так как строки Python неизменяемы. Он наследует 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])

Изменить позицию потока на заданный 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' заменяет некорректные данные на обратную косую черту с escape-последовательностью. При записи можно использовать 'xmlcharrefreplace' (замените соответствующим XML-символом) или 'namereplace' (замените \N{...} escape-последовательностями). Любое другое имя обработки ошибок, зарегистрированное в 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

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

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

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

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

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

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

getvalue()

Возвращает строку, содержащую всё содержимое буфера. Новые строки декодируются так, как если бы это делал 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.

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

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

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

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

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

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

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

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

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

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

Объекты TextIOWrapper не безопасны в многопоточных приложениях.

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

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

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