15.2. io – основные инструменты для работы с потоками¶io – Core tools for working with streams

15.2.1. Интерфейс модуля¶Module Interface

io.DEFAULT_BUFFER_SIZE¶

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

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

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

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

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

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

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

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

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' (замена на 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' преобразуются в указанную строку.

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

15.2.2. Базовые классы ввода-вывода¶I/O Base Classes

class io.IOBase¶

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

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

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

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

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

15.2.3. Низкоуровневый файловый ввод-вывод¶Raw File I/O

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

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

Параметр name может быть одним из двух:

• строка, представляющая путь к открываемому файлу;

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

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

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

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

mode¶

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

name¶

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

15.2.4. Буферизированные потоки¶Buffered Streams

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

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

read1(n)¶

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

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

• когда буфер становится слишком мал для всех ожидающих данных;

• когда вызывается flush();

• когда запрашивается seek() (для объектов BufferedRandom);

• когда объект BufferedWriter закрывается или уничтожается.

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

15.2.5. Текстовый ввод-вывод¶Text I/O

class io.TextIOBase¶

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

# Извлечь содержимое файла – это будет
# u'Первая строка.\nВторая строка.\n'
contents = output.getvalue()

# Закрыть объект и освободить буфер памяти –
# .getvalue() теперь будет вызывать исключение.
output.close()

class io.IncrementalNewlineDecoder¶

Вспомогательный кодек для декодирования символов новой строки в режиме универсальных новых строк. Наследует codecs.IncrementalDecoder.

15.2.6. Расширенные темы¶Advanced topics

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