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

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

Обзор

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

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

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

Изменено в версии 3.3: Операции, которые раньше вызывали исключение IOError, теперь вызывают OSError, поскольку IOError теперь является псевдонимом OSError.

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

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

Проще всего создать текстовый поток с помощью open(), при необходимости указав кодировку:

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

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

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

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

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

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

Проще всего создать двоичный поток с помощью open(), указав 'b' в строке режима:

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

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

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

Подробное описание API двоичных потоков приведено в документации BufferedIOBase.

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

Необработанный ввод-вывод

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

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

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

Кодировка текста

Кодировка по умолчанию для TextIOWrapper и open() зависит от локали (locale.getencoding()).

Однако многие разработчики забывают указывать кодировку при открытии текстовых файлов в UTF-8 (например, JSON, TOML, Markdown и т. д.), поскольку на большинстве платформ Unix по умолчанию используется локаль UTF-8. Это приводит к ошибкам, так как у большинства пользователей Windows кодировка локали не UTF-8. Например:

# May not work on Windows when non-ASCII characters in the file.
with open("README.md") as f:
    long_description = f.read()

Поэтому настоятельно рекомендуется явно указывать кодировку при открытии текстовых файлов. Чтобы использовать UTF-8, передайте encoding="utf-8". Для использования кодировки текущей локали начиная с Python 3.10 поддерживается encoding="locale".

См. также

Режим UTF-8 в Python: Режим UTF-8 в Python позволяет изменить кодировку по умолчанию с зависящей от локали на UTF-8.
PEP 686: В Python 3.15 режим UTF-8 в Python будет включён по умолчанию.

Включение предупреждений о кодировке

Добавлено в версии 3.10: Подробнее см. PEP 597.

Чтобы узнать, где используется кодировка локали по умолчанию, можно включить параметр командной строки -X warn_default_encoding или задать переменную среды PYTHONWARNDEFAULTENCODING. При использовании кодировки по умолчанию будет выдаваться предупреждение EncodingWarning.

Если вы предоставляете API, который использует open() или TextIOWrapper и передаёт encoding=None в качестве параметра, можно использовать text_encoding(), чтобы вызывающие API получали предупреждение EncodingWarning, если не передают encoding. Однако для новых API рекомендуется использовать UTF-8 по умолчанию (то есть encoding="utf-8").

Высокоуровневый интерфейс модуля

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

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

Это псевдоним встроенной функции open().

Эта функция вызывает событие аудита open с аргументами path, mode и flags. Аргументы mode и flags могли быть изменены или определены по исходному вызову.

io.open_code(path)

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

path должен быть объектом str и абсолютным путём.

Поведение этой функции может быть переопределено более ранним вызовом PyFile_SetOpenCodeHook(). Однако при условии, что path является объектом str и абсолютным путём, open_code(path) всегда должна работать так же, как open(path, 'rb'). Переопределение поведения предназначено для дополнительной проверки или предварительной обработки файла.

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

io.text_encoding(encoding, stacklevel=2, /)

Это вспомогательная функция для вызываемых объектов, использующих open() или TextIOWrapper и имеющих параметр encoding=None.

Функция возвращает encoding, если оно не равно None. В противном случае она возвращает "locale" или "utf-8" в зависимости от режима UTF-8.

Функция выдаёт предупреждение EncodingWarning, если sys.flags.warn_default_encoding имеет значение true, а encoding равно None. Параметр stacklevel указывает место выдачи предупреждения. Например:

def read_text(path, encoding=None):
    encoding = io.text_encoding(encoding)  # stacklevel=2
    with open(path, encoding) as f:
        return f.read()

В этом примере предупреждение EncodingWarning выдаётся для вызывающего кода read_text().

Дополнительную информацию см. в разделе Кодировка текста.

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

Изменено в версии 3.11: text_encoding() возвращает «utf-8», если включён режим UTF-8, а encoding равно None.

exception io.BlockingIOError: Это псевдоним для совместимости со встроенным исключением BlockingIOError.

exception io.UnsupportedOperation: Исключение, наследующее OSError и ValueError. Оно вызывается при выполнении неподдерживаемой операции над потоком.

См. также

sys: содержит стандартные потоки ввода-вывода: sys.stdin, sys.stdout и sys.stderr.

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

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

Примечание

Абстрактные базовые классы также предоставляют реализации некоторых методов по умолчанию, чтобы упростить реализацию конкретных классов потоков. Например, BufferedIOBase предоставляет неоптимизированные реализации readinto() и readline().

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

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

ABC BufferedIOBase расширяет IOBase. Он предназначен для буферизации необработанного двоичного потока (RawIOBase). Его подклассы — BufferedWriter, BufferedReader и BufferedRWPair — буферизуют необработанные двоичные потоки, доступные соответственно для записи, чтения и для чтения и записи. BufferedRandom предоставляет буферизованный интерфейс к потокам с поддержкой позиционирования. Другой подкласс BufferedIOBase, BytesIO, представляет собой поток байтов в памяти.

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

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

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

ABC	Наследует	Заглушки методов	Методы и свойства-примеси
`IOBase`		`fileno`, `seek` и `truncate`	`close`, `closed`, `__enter__`, `__exit__`, `flush`, `isatty`, `__iter__`, `__next__`, `readable`, `readline`, `readlines`, `seekable`, `tell`, `writable` и `writelines`
`RawIOBase`	`IOBase`	`readinto` и `write`	Унаследованные методы `IOBase`, `read` и `readall`
`BufferedIOBase`	`IOBase`	`detach`, `read`, `read1` и `write`	Унаследованные методы `IOBase`, `readinto` и `readinto1`
`TextIOBase`	`IOBase`	`detach`, `read`, `readline` и `write`	Унаследованные методы `IOBase`, `encoding`, `errors` и `newlines`

Базовые классы ввода-вывода

class io.IOBase

Абстрактный базовый класс для всех классов ввода-вывода.

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

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

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

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

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

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

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

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

close()

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

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

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

fileno(): Вернуть дескриптор файла (целое число), лежащий в основе потока, если он существует. Если объект ввода-вывода не использует дескриптор файла, возбуждается исключение OSError.

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

isatty(): Вернуть True, если поток является интерактивным (то есть подключён к терминалу или устройству tty).

readable(): Вернуть True, если из потока можно читать. Если False, вызов read() приведёт к возбуждению исключения OSError.

readline(size=-1, /)

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

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

readlines(hint=-1, /)

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

Значения hint, равные 0 или меньше, а также None трактуются как отсутствие ограничения.

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

seek(offset, whence=os.SEEK_SET, /)

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

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

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

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

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

tell(): Вернуть текущую позицию в потоке.

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

Изменено в версии 3.5: Теперь в Windows при увеличении размера файлы заполняются нулями.

writable(): Вернуть True, если поток поддерживает запись. Если False, вызовы write() и truncate() приведут к возбуждению исключения OSError.

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

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

class io.RawIOBase

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

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

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

read(size=-1, /)

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

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

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

readall(): Считать и вернуть все байты из потока до конца файла, при необходимости выполнив несколько вызовов потока.

readinto(b, /): Считать байты в предварительно выделенный, доступный для записи объект, подобный байтам b и вернуть количество считанных байтов. Например, b может быть объектом bytearray. Если объект работает в неблокирующем режиме и доступных байтов нет, возвращается None.

write(b, /): Записать переданный объект, подобный байтам b в базовый необработанный поток и вернуть количество записанных байтов. В зависимости от особенностей базового необработанного потока, особенно если он работает в неблокирующем режиме, это количество может быть меньше длины b в байтах. Если необработанный поток настроен на неблокирующий режим и ни один байт не может быть записан сразу, возвращается None. После возврата из этого метода вызывающий код может освободить или изменить b, поэтому реализация должна обращаться к b только во время вызова метода.

class io.BufferedIOBase

Базовый класс для двоичных потоков, поддерживающих буферизацию того или иного вида. Он наследует IOBase.

Основное отличие от RawIOBase заключается в том, что методы read(), readinto() и write() пытаются соответственно считать запрошенный объём данных или обработать все переданные данные, при необходимости выполняя несколько системных вызовов.

Кроме того, эти методы могут возбуждать исключение BlockingIOError, если базовый необработанный поток работает в неблокирующем режиме и не может принять или предоставить достаточно данных; в отличие от соответствующих методов RawIOBase, они никогда не возвращают None.

Кроме того, метод read() не имеет реализации по умолчанию, делегирующей вызов методу readinto().

Обычно реализация BufferedIOBase не должна наследовать реализацию RawIOBase, а должна оборачивать её, как это делают BufferedWriter и BufferedReader.

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

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

detach()

Отсоединить базовый необработанный поток от буфера и вернуть его.

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

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

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

read(size=-1, /)

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

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

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

read1(size=-1, /)

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

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

readinto(b, /)

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

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

readinto1(b, /)

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

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

write(b, /)

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

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

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

Низкоуровневый ввод-вывод файлов

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

Необработанный двоичный поток, представляющий файл уровня ОС, содержащий байтовые данные. Он наследуется от RawIOBase.

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

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

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

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

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

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

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

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

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

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

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

name: Имя файла. Если в конструкторе не указано имя, это файловый дескриптор файла.

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

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

class io.BytesIO(initial_bytes=b'')

Двоичный поток, использующий буфер байтов в памяти. Он наследуется от 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(size=-1, /): Для BytesIO этот метод совпадает с read().

Изменено в версии 3.7: Аргумент size теперь необязательный.

readinto1(b, /): Для BytesIO этот метод совпадает с readinto().

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

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

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

peek(size=0, /): Возвращает байты из потока, не перемещая позицию. Для выполнения вызова выполняется не более одного чтения из необработанного потока. Число возвращённых байтов может быть меньше или больше запрошенного.

read(size=-1, /): Читает и возвращает size байт либо, если size не задан или отрицателен, читает до конца файла или до блокировки вызова чтения в неблокирующем режиме.

read1(size=-1, /): Читает и возвращает не более size байт, выполняя только один вызов для необработанного потока. Если в буфере есть хотя бы один байт, возвращаются только буферизованные байты. В противном случае выполняется один вызов чтения из необработанного потока.

Изменено в версии 3.7: Аргумент size теперь необязательный.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

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

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

flush(): Принудительно записывает байты из буфера в необработанный поток. Если необработанный поток блокирует запись, должна быть вызвана ошибка BlockingIOError.

write(b, /): Записывает объект, подобный bytes, b, и возвращает число записанных байтов. В неблокирующем режиме ошибка BlockingIOError вызывается, если буфер необходимо записать, но необработанный поток блокирует запись.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буферизованный двоичный поток, предоставляющий доступ более высокого уровня к позиционируемому необработанному двоичному потоку RawIOBase. Он наследуется от BufferedReader и BufferedWriter.

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

BufferedRandom поддерживает все возможности BufferedReader и BufferedWriter. Кроме того, гарантируется реализация методов seek() и tell().

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

Буферизованный двоичный поток, предоставляющий доступ более высокого уровня к двум непозиционируемым необработанным двоичным потокам RawIOBase: один доступен для чтения, другой — для записи. Он наследуется от BufferedIOBase.

reader и writer — объекты RawIOBase, доступные соответственно для чтения и записи. Если buffer_size не указан, по умолчанию используется DEFAULT_BUFFER_SIZE.

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

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

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

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

class io.TextIOBase

Базовый класс для текстовых потоков. Этот класс предоставляет интерфейс потокового ввода-вывода на основе символов и строк. Он наследуется от IOBase.

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

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

errors: Параметр обработки ошибок декодера или кодировщика.

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

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

detach()

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

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

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

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

read(size=-1, /): Считывает из потока и возвращает не более size символов в виде единого значения str. Если size отрицательно или равно None, чтение продолжается до EOF.

readline(size=-1, /)

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

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

seek(offset, whence=SEEK_SET, /)

Перемещает позицию в потоке на заданное значение offset. Поведение зависит от параметра whence. Значение параметра whence по умолчанию — SEEK_SET.

SEEK_SET или 0: перемещает позицию от начала потока (значение по умолчанию); offset должен быть либо числом, возвращённым TextIOBase.tell(), либо нулём. Любое другое значение offset приводит к неопределённому поведению.
SEEK_CUR или 1: «перемещает» позицию к текущему месту; offset должен быть равен нулю, что не приводит к действиям (все остальные значения не поддерживаются).
SEEK_END или 2: перемещает позицию в конец потока; offset должен быть равен нулю (все остальные значения не поддерживаются).

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

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

tell(): Возвращает текущую позицию в потоке в виде непрозрачного числа. Обычно это число не соответствует количеству байтов в базовом двоичном хранилище.

write(s, /): Записывает строку s в поток и возвращает количество записанных символов.

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

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

encoding задаёт название кодировки, используемой для декодирования или кодирования потока. По умолчанию используется locale.getencoding(). Для явного указания кодировки текущей локали можно использовать encoding="locale". Дополнительные сведения см. в разделе Кодировка текста.

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 равен '', режим универсальной обработки переводов строк включается, но окончания строк возвращаются вызывающему коду без преобразования. Если newline имеет любое другое допустимое значение, строки ввода завершаются только указанной строкой, а окончание строки возвращается вызывающему коду без преобразования.
При записи данных в поток, если newline равен None, любые записанные символы '\n' преобразуются в системный разделитель строк по умолчанию, os.linesep. Если newline равен '' или '\n', преобразование не выполняется. Если newline имеет любое другое допустимое значение, все записанные символы '\n' преобразуются в указанную строку.

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

Если write_through равен True, вызовы write() гарантированно не буферизуются: любые данные, записанные в объект TextIOWrapper, немедленно передаются в его базовый двоичный buffer.

Изменено в версии 3.3: Добавлен аргумент write_through.

Изменено в версии 3.3: Теперь кодировка encoding по умолчанию — locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Не изменяйте временно кодировку локали с помощью locale.setlocale(), используйте кодировку текущей локали вместо предпочтительной кодировки пользователя.

Изменено в версии 3.10: Аргумент encoding теперь поддерживает фиктивное имя кодировки "locale".

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

line_buffering: Указывает, включена ли буферизация строк.

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

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

reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)

Перенастраивает этот текстовый поток, задавая новые значения параметров encoding, errors, newline, line_buffering и write_through.

Для параметров, которые не указаны, сохраняются текущие значения, за исключением случая, когда указан encoding, но не указан errors: тогда используется errors='strict'.

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

Перед установкой новых параметров этот метод неявно сбрасывает поток.

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

Изменено в версии 3.11: Метод поддерживает параметр encoding="locale".

seek(cookie, whence=os.SEEK_SET, /)

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

Поддерживаются четыре операции, задаваемые следующими комбинациями аргументов:

seek(0, SEEK_SET): перемещение в начало потока.
seek(cookie, SEEK_SET): восстановление предыдущей позиции; cookie должен быть числом, возвращённым tell().
seek(0, SEEK_END): быстрое перемещение в конец потока.
seek(0, SEEK_CUR): сохранение текущей позиции в потоке.

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

См. также

os.SEEK_SET, os.SEEK_CUR и os.SEEK_END.

tell(): Возвращает позицию в потоке в виде непрозрачного числа. Возвращаемое значение tell() можно передать в качестве входных данных в seek(), чтобы восстановить предыдущую позицию в потоке.

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

Текстовый поток, использующий текстовый буфер в памяти. Он наследуется от TextIOBase.

Текстовый буфер удаляется при вызове метода close().

Исходное значение буфера можно задать с помощью параметра initial_value. Если преобразование переводов строк включено, переводы строк будут закодированы так же, как при вызове write(). Поток устанавливается в начало буфера, что имитирует открытие существующего файла в режиме w+ и позволяет сразу записывать данные с начала или перезаписывать исходное значение. Чтобы имитировать открытие файла в режиме a+ с готовностью к добавлению данных, используйте f.seek(0, io.SEEK_END), чтобы переместить поток в конец буфера.

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

StringIO предоставляет следующий метод в дополнение к методам TextIOBase и IOBase:

getvalue(): Возвращает значение str, содержащее всё содержимое буфера. Переводы строк декодируются так же, как при вызове read(), однако позиция в потоке не изменяется.

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

import io

output = io.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()

class io.IncrementalNewlineDecoder: Вспомогательный кодек, декодирующий переводы строк для режима универсальной обработки переводов строк. Он наследуется от codecs.IncrementalDecoder.

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

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

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

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

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

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

Однако StringIO — это встроенный контейнер Юникода в памяти, скорость работы которого будет сопоставима со скоростью BytesIO.

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

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

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

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

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

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

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