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

Модуль io предоставляет Python-интерфейсы для обработки потоков. В Python 2.x он предлагается в качестве альтернативы встроенному объекту file, а в Python 3.x он является стандартным интерфейсом для доступа к файлам и потокам.

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

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

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

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

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

1. Интерфейс модуля

io.DEFAULT_BUFFER_SIZE

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

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

Открыть файл и вернуть соответствующий поток. Если файл не может быть открыт, генерируется исключение IOError.

Файл может быть строкой, содержащей путь (абсолютный или относительный к текущей рабочей директории) открываемого файла, или целочисленным дескриптором файла, который нужно обернуть. (Если указан дескриптор файла, он будет закрыт при закрытии возвращённого объекта ввода-вывода, если не задано closefd равным False.)

Режим — это необязательная строка, определяющая режим открытия файла. По умолчанию используется 'r' , что означает открытие для чтения в текстовом режиме. Другие распространённые значения — 'w' для записи (обнуление файла, если он уже существует), и 'a' для добавления (что на некоторых Unix-системах означает, что все записи добавляются в конец файла независимо от текущей позиции поиска). В текстовом режиме, если кодировка не задана, используемая кодировка зависит от платформы. (Для чтения и записи необработанных байтов используйте двоичный режим и не указывайте кодировку.) Доступные режимы:

Символ	Значение
'r'	открытие для чтения (по умолчанию)
'w'	открытие для записи, предварительно обнуляя файл
'a'	открытие для записи, добавление в конец файла, если он существует
'b'	двоичный режим
't'	текстовый режим (по умолчанию)
'+'	открытие файла для обновления (чтения и записи)
'U'	режим универсальных новых строк (для обратной совместимости; не следует использовать в новом коде)

Режим по умолчанию — 'rt' (открытие для чтения текста). Для двоичного произвольного доступа режим 'w+b' открывает и обнуляет файл до 0 байтов, а 'r+b' открывает файл без обнуления.

Python различает файлы, открытые в двоичном и текстовом режимах, даже если операционная система этого не делает. Файлы, открытые в двоичном режиме (включая 'b' в аргументе mode), возвращают содержимое как bytes объекты без какой-либо декодировки. В текстовом режиме (по умолчанию или когда 't' включено в аргумент mode) содержимое файла возвращается как unicode строки, при этом байты сначала декодируются с использованием платформенно-зависимой кодировки или с использованием заданной кодировки, если она указана.

buffering — это необязательное целое число, используемое для установки политики буферизации. Передайте 0, чтобы отключить буферизацию (разрешено только в двоичном режиме), 1, чтобы выбрать построчную буферизацию (только в текстовом режиме), и целое число > 1, чтобы указать размер буфера фиксированного размера. Если аргумент buffering не указан, политика буферизации по умолчанию работает следующим образом:

• Двоичные файлы буферизуются кусками фиксированного размера; размер буфера выбирается с помощью эвристики, пытающейся определить «размер блока» базового устройства и переходя к DEFAULT_BUFFER_SIZE. На многих системах размер буфера обычно составляет 4096 или 8192 байта.
• «Интерактивные» текстовые файлы (файлы, для которых isatty() возвращает True) используют построчную буферизацию. Другие текстовые файлы используют политику, описанную выше для двоичных файлов.

encoding — это имя кодировки, используемой для декодирования или кодирования файла. Это должно использоваться только в текстовом режиме. Кодировка по умолчанию зависит от платформы (то, что возвращает locale.getpreferredencoding()), но может использоваться любая кодировка, поддерживаемая Python. Список поддерживаемых кодировок см. в модуле codecs.

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

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

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

Если closefd равно False и был передан дескриптор файла, а не имя файла, то базовый дескриптор файла останется открытым при закрытии файла. Если задано имя файла, closefd не влияет и должно быть True (по умолчанию).

Тип объекта файла, возвращаемого функцией open(), зависит от режима. Когда open() используется для открытия файла в текстовом режиме ('w', 'r', 'wt', 'rt', и т.д.), он возвращает подкласс TextIOBase (конкретно TextIOWrapper). При использовании для открытия файла в двоичном режиме с буферизацией возвращаемый класс является подклассом BufferedIOBase. Точный класс варьируется: в режиме чтения двоичных данных возвращается BufferedReader; в режимах записи и добавления двоичных данных возвращается BufferedWriter, а в режимах чтения/записи возвращается BufferedRandom. При отключенной буферизации возвращается исходный поток, подкласс RawIOBase, FileIO.

Также можно использовать строку unicode или bytes в качестве файла для чтения и записи. Для строк unicode можно использовать StringIO как файл, открытый в текстовом режиме, а для bytes — BytesIO как файл, открытый в двоичном режиме.

exception io.BlockingIOError

Исключение, генерируемое при блокировке в неблокирующем потоке. Оно наследуется от IOError.

Помимо атрибутов IOError, BlockingIOError имеет один атрибут:

characters_written

Целое число, содержащее количество символов, записанных в поток перед блокировкой.

exception io.UnsupportedOperation

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

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

class io.IOBase

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

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

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

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

Изменено в версии 2.7: Реализации должны поддерживать аргументы memoryview.

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

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

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

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

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

close()

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

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

closed

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

fileno()

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

flush()

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

isatty()

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

readable()

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

readline(limit=-1)

Считывает и возвращает одну строку из потока. Если указан limit, будет считано не более limit байтов.

Разделитель строк всегда 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 обычно отрицательный

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

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

seekable()

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

tell()

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

truncate(size=None)

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

writable()

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

writelines(lines)

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

__del__()

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

class io.RawIOBase

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

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

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

read(n=-1)

Прочитать до n байт из объекта и вернуть их. Для удобства, если n не указано или равно -1, вызывается readall(). В противном случае выполняется только один системный вызов. Может быть возвращено меньше, чем n байт, если системный вызов вернул меньше, чем n байт.

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

readall()

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

readinto(b)

Прочитать до len(b) байт в b и вернуть количество прочитанных байт. Объект b должен быть предварительно выделенным, записываемым массивом байтов, либо bytearray, либо memoryview. Если объект находится в режиме без блокировки и байты недоступны, возвращается None.

write(b)

Записать b в базовый поток сырых данных и вернуть количество записанных байт. Объект b должен быть массивом байтов, либо bytes, bytearray, либо memoryview. Возвращаемое значение может быть меньше len(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.

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

read(n=-1)

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

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

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

read1(n=-1)

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

readinto(b)

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

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

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

write(b)

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

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

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

3. Ввод-вывод ссылок на сырые файлы

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

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

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

• строка, представляющая путь к файлу, который будет открыт;
• целое число, представляющее номер существующего дескриптора файла на уровне операционной системы, к которому получившийся объект FileIO предоставит доступ.

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

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

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

mode

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

name

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

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

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

class io.BytesIO([initial_bytes])

Реализация потока, использующая буфер байтов в памяти. Наследует BufferedIOBase.

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

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

getvalue()

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

read1()

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

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

peek([n])

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

read([n])

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

read1(n)

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

Третий аргумент max_buffer_size поддерживается, но не используется и устарел.

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

flush()

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

write(b)

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

Третий аргумент, max_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.

Четвёртый аргумент, max_buffer_size, поддерживается, но не используется и устарел.

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

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

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

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

class io.TextIOBase

Базовый класс для текстовых потоков. Этот класс предоставляет интерфейс для ввода-вывода потоков на основе символов и строк Юникода. Метод readinto() отсутствует, так как строки Python unicode неизменяемы. Он наследует от IOBase. Публичного конструктора нет.

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

encoding

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

errors

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

newlines

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

buffer

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

detach()

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

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

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

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

read(n=-1)

Прочитать и вернуть не более n символов из потока как одиночную строку unicode. Если n отрицательно или None, читает до конца потока.

readline(limit=-1)

Считывает до символа новой строки или конца потока и возвращает строку unicode. Если поток уже достиг конца, возвращается пустая строка.

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

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 должен быть нулём (все остальные значения не поддерживаются).

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

Введено в версии 2.7: Константы SEEK_*.

tell()

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

write(s)

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

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

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

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

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

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

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

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

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

line_buffering

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

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

Поток в оперативной памяти для текстовых данных Unicode. Он наследует TextIOWrapper.

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

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

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

getvalue()

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

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

import io

output = io.StringIO()
output.write(u'First line.\n')
output.write(u'Second line.\n')

# Retrieve file contents -- this will be
# u'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.

6. Дополнительные темы

Здесь мы обсудим несколько дополнительных тем, относящихся к конкретным реализациям ввода-вывода, описанным выше.

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

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

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

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

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

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

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

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

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

TextIOWrapper объекты не потокобезопасны.

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

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

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