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.getpreferredencoding(False)).

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

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

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

Если вам нужно запустить существующий код в Windows, который пытается открыть файлы UTF-8 с использованием кодировки локали по умолчанию, вы можете включить режим UTF-8. См. Режим UTF-8 в Windows.

Включение предупреждения 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.

Эта функция возвращает кодировку, если она не None, и "locale", если кодировка равна None.

Эта функция выводит EncodingWarning, если sys.flags.warn_default_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.

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. В этом примере файл закрывается после завершения блока оператора 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=SEEK_SET, /)

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

SEEK_SET или 0 — начало потока (по умолчанию); offset должен быть нулём или положительным
SEEK_CUR или 1 — текущая позиция потока; offset может быть отрицательным
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() экземпляра.

END_OF_DOCUMENT_MARKER

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, /)

Считывает байты в предварительно выделенный, доступный для записи объект типа байтов 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).

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

См. встроенную функцию 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 не пытается синхронизировать доступ к исходным потокам. Не следует передавать ему один и тот же объект как для чтения, так и для записи; используйте 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.getpreferredencoding(False). 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 нет.

Изменить кодировку или newline невозможно, если из потока уже были прочитаны какие-либо данные. С другой стороны, изменение кодировки после записи возможно.

Этот метод выполняет неявную очистку потока перед настройкой новых параметров.

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

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

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

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

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

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

StringIO предоставляет этот метод в дополнение к методам из TextIOBase и IOBase:

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

Текстовый Ввод/Вывод

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

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

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

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

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

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

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

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

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