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.

См. также

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

Включение предупреждения EncodingWarning

Новое в версии 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 истинно, а 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, если они не поддерживают данную операцию.

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

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

Другой подкласс BufferedIOBase, BytesIO, представляет собой поток байтов в памяти.

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

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

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

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

readinto1(b, /)

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

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

Новое в версии 3.5.

write(b, /)

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

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

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

Потоковый ввод-вывод необработанных файлов

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

Поток необработанных бинарных данных, представляющий файл на уровне операционной системы. Наследует RawIOBase.

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

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

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

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

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

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

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

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

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

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

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, /): Прочитать и вернуть не более размер символов из потока как единую str. Если размер отрицательный или None, считывает до конца файла.

readline(size=- 1, /)

Прочитать до новой строки или конца файла и вернуть одиночную str. Если поток уже достиг конца файла, возвращается пустая строка.

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

seek(offset, whence=SEEK_SET, /)

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

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

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

Новое в версии 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.

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