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

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

1. Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.1. Классы базовых I/O

class io.IOBase

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

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

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

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

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

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

readlines(hint=-1)

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

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

seek(offset[, whence])

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

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

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

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

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

seekable()

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

tell()

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

truncate(size=None)

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

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

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

readall()

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

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 только во время вызова метода.

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

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

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

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

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

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

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

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

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

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

Изменено в версии 3.3: Добавлен параметр opener. Добавлена 'x' режим.

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

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

mode

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

name

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

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.

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)

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

Изменено в версии 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()

Возвращает 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.

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

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

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

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

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

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

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

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

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

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

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

4.4. Рекурсивный доступ

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

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