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

См. также

Режим 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.

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

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

END_OF_DOCUMENT_MARKER

Классы базового ввода/вывода

class io.IOBase

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

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

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

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

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

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

IOBase также является менеджером контекста и, следовательно, поддерживает оператор with. В этом примере file закрывается после завершения блока оператора with, даже если произошла ошибка:

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

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

close()

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

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

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

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

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

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

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

readline(size=-1, /)

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

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

readlines(hint=-1, /)

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

Значения подсказки, равные или меньшие 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, /): Изменяет размер потока на указанный размер в байтах (или на текущую позицию, если размер не указан). Текущая позиция потока не изменяется. Это изменение размера может расширить или уменьшить текущий размер файла. В случае расширения содержимое новой области файла зависит от платформы (на большинстве систем дополнительные байты заполняются нулями). Возвращается новый размер файла.
Изменено в версии 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, /): Считывает байты в предварительно выделенный, записываемый объект типа bytes b и возвращает количество считанных байтов. Например, b может быть bytearray. Если объект находится в режиме без блокировки и доступных байтов нет, возвращается None.

write(b, /): Записывает заданный объект типа bytes, 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 — это объект типа 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, /): Записывает объект типа 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{...} последовательностями escape) могут использоваться. Любое другое имя обработки ошибок, зарегистрированное с помощью 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.

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

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

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

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

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

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

См. также

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

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

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

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

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

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

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

StringIO предоставляет этот метод помимо тех, что доступны в TextIOBase и IOBase:

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

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

import io

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

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

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

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

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

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

Бинарный ввод-вывод

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

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

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

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

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

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

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

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

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

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

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