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". Для использования текущей кодировки локали поддержка encoding="locale" появилась в Python 3.10.

См. также

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

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

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

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

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

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, /): Записывает байтоподобный объект 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, чтение продолжается до конца файла.

readline(size=-1, /)

Читает данные до перевода строки или конца файла и возвращает одну строку str. Если поток уже находится в конце файла, возвращается пустая строка.

Если задано значение 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_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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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