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. Это приводит к ошибкам, поскольку кодировка локали не UTF-8 для большинства пользователей Windows. Например:

# 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 значением по умолчанию.

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

Добавлено в версии 3.10: См. PEP 597 для получения более подробной информации.

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

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

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

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 с аргументами путь, режим и флаги. Аргументы режим и флаги могут быть изменены или выведены из исходного вызова.

io.open_code(path)

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

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

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

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

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

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

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

Эта функция генерирует 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.

Изменено в версии 3.11: text_encoding() возвращает “utf-8”, когда режим UTF-8 включен и кодировка None.

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

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

См. также

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

END_OF_DOCUMENT_MARKER

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

Реализация потоков ввода-вывода организована как иерархия классов. Сначала абстрактные базовые классы (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, /)

Изменить позицию потока на заданный байтовый смещение, интерпретируемое относительно позиции, указанной 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() экземпляра.

END_OF_DOCUMENT_MARKER

class io.RawIOBase

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

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

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

read(size=-1, /)

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

BytesIO предоставляет или переопределяет эти методы в дополнение к методам из BufferedIOBase и IOBase:

getbuffer()

Возвращает доступ к содержимому буфера для чтения и записи без копирования. Также изменение этого доступа прозрачно обновит содержимое буфера:

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

Примечание

Пока существует доступ, объект BytesIO нельзя изменять размер или закрывать.

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

getvalue(): Возвращает bytes, содержащий всё содержимое буфера.

read1(size=-1, /): В BytesIO это то же самое, что и read().

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

readinto1(b, /): В BytesIO это то же самое, что и readinto().

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

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

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

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

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

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

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

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

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

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

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

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

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

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

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

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

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

Текстовые потоки ввода/вывода

class io.TextIOBase

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

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

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

errors: Настройки обработки ошибок декодера или кодировщика.

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

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

detach()

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

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

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

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

read(size=-1, /): Прочитать и вернуть не более size символов из потока как единую str. Если size отрицательно или None, читается до конца потока.

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 содержит символ новой строки или возврата каретки.

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

Изменено в версии 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.

Изменено в версии 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() также.