io — Основные средства для работы с потоками

Исходный код: Lib/io.py

Обзор

Модуль io предоставляет основные средства Python для работы с различными типами ввода-вывода. Существует три основных типа ввода-вывода: текстовый ввод-вывод, двоичный ввод-вывод и необработанный ввод-вывод. Это общие категории, и для каждой из них можно использовать различные хранилища данных. Конкретный объект, принадлежащий к любой из этих категорий, называется file object. Также часто используются термины поток и объект, подобный файлу.

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

Все потоки строго следят за типом передаваемых им данных. Например, передача объекта 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")

Примечание

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

Подробное описание API текстовых потоков приведено в документации к TextIOBase.

Двоичный ввод-вывод

Двоичный ввод-вывод (также называемый буферизованным вводом-выводом) принимает bytes-like objects и создаёт объекты 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.

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

Необработанный ввод-вывод — это низкоуровневый интерфейс, и обычно необходимо проверять возвращаемые методами значения и явно повторять вызовы, чтобы гарантировать завершение операции. Например, write() возвращает количество записанных байтов, которое может быть меньше количества переданных байтов (частичная запись). Объекты высокоуровневого ввода-вывода, такие как двоичный ввод-вывод и текстовый ввод-вывод, реализуют повторные попытки.

Кодировка текста

Кодировка по умолчанию для TextIOWrapper и open() зависит от локали (locale.getencoding()).

Однако многие разработчики забывают указывать кодировку при открытии текстовых файлов в UTF-8 (например, JSON, TOML, Markdown и т. д.), поскольку на большинстве платформ Unix по умолчанию используется локаль UTF-8. Это приводит к ошибкам, так как у большинства пользователей Windows кодировка локали не UTF-8. Например:

# May not work on Windows when non-ASCII characters in the file.
with open("README.md") as f:
    long_description = f.read()

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

См. также

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

Необязательное предупреждение EncodingWarning

Добавлено в версии 3.10: Подробнее см. PEP 597.

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

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

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

io.DEFAULT_BUFFER_SIZE: Целое число, содержащее размер буфера по умолчанию, используемый классами буферизованного ввода-вывода модуля. open() по возможности использует размер блока файла (определяемый с помощью os.stat()).

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Это псевдоним встроенной функции open().

Эта функция вызывает событие аудита open с аргументами path, mode и flags. Аргументы mode и flags могли быть изменены или определены на основе исходного вызова.

io.open_code(path)

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

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

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

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

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

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

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

Эта функция выдаёт предупреждение EncodingWarning, если sys.flags.warn_default_encoding имеет значение true, а encoding равен None. Параметр stacklevel указывает, где выдаётся предупреждение. Например:

def read_text(path, encoding=None):
    encoding = io.text_encoding(encoding)  # stacklevel=2
    with open(path, encoding) as f:
        return f.read()

В этом примере предупреждение EncodingWarning выдаётся для вызывающего объекта read_text().

Дополнительные сведения см. в разделе Кодировка текста.

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

Изменено в версии 3.11: text_encoding() возвращает «utf-8», если включён режим UTF-8, а encoding равен None.

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

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

См. также

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

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

Реализация потоков ввода-вывода организована в виде иерархии классов. Сначала идут абстрактные базовые классы (ABC), которые используются для определения различных категорий потоков, а затем конкретные классы, предоставляющие стандартные реализации потоков.

Примечание

Абстрактные базовые классы также предоставляют реализации по умолчанию для некоторых методов, чтобы упростить создание конкретных классов потоков. Например, BufferedIOBase предоставляет неоптимизированные реализации readinto() и readline().

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

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

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

ABC TextIOBase расширяет IOBase. Он обеспечивает работу с потоками, байты которых представляют текст, и выполняет кодирование и декодирование строк. TextIOWrapper, расширяющий TextIOBase, представляет собой буферизованный текстовый интерфейс к буферизованному необработанному потоку (BufferedIOBase). Наконец, StringIO — это текстовый поток в памяти.

Имена аргументов не являются частью спецификации, и только аргументы open() предназначены для использования в качестве именованных аргументов.

В следующей таблице приведены ABC, предоставляемые модулем io:

ABC	Наследуется от	Методы-заглушки	Методы и свойства примесей
`IOBase`		`fileno`, `seek` и `truncate`	`close`, `closed`, `__enter__`, `__exit__`, `flush`, `isatty`, `__iter__`, `__next__`, `readable`, `readline`, `readlines`, `seekable`, `tell`, `writable` и `writelines`
`RawIOBase`	`IOBase`	`readinto` и `write`	Унаследованные методы `IOBase`, `read` и `readall`
`BufferedIOBase`	`IOBase`	`detach`, `read`, `read1` и `write`	Унаследованные методы `IOBase`, `readinto` и `readinto1`
`TextIOBase`	`IOBase`	`detach`, `read`, `readline` и `write`	Унаследованные методы `IOBase`, `encoding`, `errors` и `newlines`

Базовые классы ввода-вывода

class io.IOBase

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

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

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

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

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

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

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

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

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

close()

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

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

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

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

flush(): Сбрасывает буферы записи потока, если это применимо. Для потоков только для чтения и неблокирующих потоков метод ничего не делает.

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

readable(): Возвращает True, если поток доступен для чтения. Если False, вызов read() приведёт к исключению OSError.

readline(size=-1, /)

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

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

readlines(hint=-1, /)

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

Значения hint, равные 0 или меньше, а также None, считаются отсутствием подсказки.

Обратите внимание, что объекты файлов уже можно перебирать с помощью for line in file: ... без вызова file.readlines().

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

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

os.SEEK_SET или 0 — начало потока (значение по умолчанию); offset должен быть равен нулю или быть положительным
os.SEEK_CUR или 1 — текущая позиция в потоке; offset может быть отрицательным
os.SEEK_END или 2 — конец потока; обычно offset является отрицательным

Добавлено в версии 3.1: Константы SEEK_*.

Добавлено в версии 3.3: Некоторые операционные системы могут поддерживать дополнительные значения, например os.SEEK_HOLE или os.SEEK_DATA. Допустимые значения для файла могут зависеть от того, открыт ли он в текстовом или двоичном режиме.

seekable(): Возвращает True, если поток поддерживает произвольный доступ. Если False, вызовы seek(), tell() и truncate() приведут к исключению OSError.

tell(): Возвращает текущую позицию в потоке.

truncate(size=None, /): Изменяет размер потока до заданного значения size в байтах (или до текущей позиции, если size не задан). Текущая позиция в потоке не меняется. При изменении размера текущий файл может быть расширен или уменьшен. При расширении содержимое новой области файла зависит от платформы (в большинстве систем дополнительные байты заполняются нулями). Возвращается новый размер файла.

Изменено в версии 3.5: Теперь Windows заполняет файлы нулями при расширении.

writable(): Возвращает True, если поток поддерживает запись. Если False, вызовы write() и truncate() приведут к исключению OSError.

writelines(lines, /): Записывает список строк в поток. Разделители строк не добавляются, поэтому обычно каждая передаваемая строка уже содержит разделитель в конце.

__del__(): Подготавливает объект к уничтожению. IOBase предоставляет реализацию этого метода по умолчанию, которая вызывает метод close() экземпляра.

class io.RawIOBase

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

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

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

read(size=-1, /)

Читает из объекта и возвращает до size байтов. Для удобства, если size не задан или равен -1, возвращаются все байты до конца файла.

Предпринимается попытка выполнить только один системный вызов, однако он будет повторён в случае прерывания, если обработчик сигнала не вызовет исключение (обоснование см. в PEP 475). Это означает, что может быть возвращено меньше size байтов, если системный вызов операционной системы вернул меньше size байтов.

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

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

readall()

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

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

readinto(b, /)

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

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

write(b, /): Записывает переданный объект, подобный байтам b в базовый необработанный поток и возвращает количество записанных байтов. В зависимости от особенностей базового необработанного потока может быть записано меньше байтов, чем содержится в b, особенно если поток работает в неблокирующем режиме. Если необработанный поток настроен на неблокирующий режим и в него нельзя сразу записать ни одного байта, возвращается None. После возврата из этого метода вызывающий код может освободить или изменить b, поэтому реализация должна обращаться к b только во время вызова метода.

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

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

class io.BufferedIOBase

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

Главное отличие от RawIOBase заключается в том, что методы read(), readinto() и write() будут пытаться соответственно прочитать запрошенный объём данных или вывести все переданные данные.

Кроме того, если базовый необработанный поток работает в неблокирующем режиме, при возврате системой результата «операция заблокировала бы выполнение» метод write() вызовет исключение BlockingIOError с атрибутом BlockingIOError.characters_written, а метод read() вернёт уже прочитанные данные или 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. Может быть выполнено несколько операций чтения; при возникновении определённых ошибок вызовы могут повторяться. Подробнее см. os.read() и PEP 475. Возврат меньшего количества байтов, чем запрошено, не означает, что конец файла наступит в ближайшее время.

При чтении максимально возможного объёма данных реализация по умолчанию использует raw.readall, если он доступен (он должен реализовывать RawIOBase.readall()); в противном случае она будет читать в цикле, пока чтение не вернёт None, пустой объект bytes или ошибку, не подлежащую повторной обработке. Для большинства потоков чтение продолжается до конца файла, но в неблокирующих потоках могут появиться новые данные.

Примечание

Если базовый необработанный поток работает в неблокирующем режиме и данные недоступны, реализации могут либо вызвать исключение BlockingIOError, либо вернуть None. Реализации io возвращают None.

read1(size=-1, /): Читает и возвращает до size байтов, вызывая readinto(), который может повторить попытку, если возникнет EINTR, согласно PEP 475. Если size равен -1 или не задан, реализация выберет для size произвольное значение.

Примечание

Если базовый необработанный поток работает в неблокирующем режиме и данные недоступны, реализации могут либо вызвать исключение BlockingIOError, либо вернуть None. Реализации io возвращают None.

readinto(b, /)

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

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

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 и реализует его низкоуровневую модель доступа. Это означает, что write() не гарантирует запись всех байтов, а read() может прочитать меньше байтов, чем запрошено, даже если в базовом файле есть дополнительные байты. Чтобы получить поведение «записать всё» и «прочитать не меньше заданного», используйте двоичный ввод-вывод.

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

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

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

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

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

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

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

FileIO — это низкоуровневый объект ввода-вывода, поэтому необходимо явно проверять возвращаемые значения его методов, таких как read() и write(), в цикле повторных попыток, чтобы реализовать поведение «записать всё» и «прочитать не меньше заданного». Высокоуровневые объекты ввода-вывода двоичного ввода-вывода и текстового ввода-вывода реализуют повторные попытки.

Изменено в версии 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, /): В BufferedReader это то же самое, что и io.BufferedIOBase.read()

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

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

Конструктор создаёт средство чтения и записи для позиционируемого необработанного потока, переданного первым аргументом. Если 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 или RawIOBase), с которым работает TextIOBase. Он не входит в API TextIOBase и может отсутствовать в некоторых реализациях.

detach()

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

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

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

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

read(size=-1, /): Считывает из потока не более size символов и возвращает их в виде одной str. Если size отрицательно или равно None, чтение продолжается до EOF.

readline(size=-1, /)

Считывает данные до символа новой строки или EOF и возвращает одну 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 задаёт название кодировки, используемой для декодирования или кодирования потока. В режиме UTF-8 по умолчанию используется UTF-8. В противном случае по умолчанию используется locale.getencoding(). Для явного указания кодировки текущей локали можно использовать encoding="locale". Дополнительные сведения см. в разделе Кодировка текста.

errors — необязательная строка, задающая способ обработки ошибок кодирования и декодирования. Передайте 'strict', чтобы при ошибке кодирования возникало исключение ValueError (значение по умолчанию None имеет тот же эффект), или передайте 'ignore', чтобы игнорировать ошибки. (Обратите внимание: игнорирование ошибок кодирования может привести к потере данных.) Значение 'replace' приводит к вставке маркера замены (например, '?') вместо некорректных данных. Значение 'backslashreplace' приводит к замене некорректных данных экранированной обратной косой чертой последовательностью. При записи можно использовать 'xmlcharrefreplace' (замена на соответствующую ссылку на символ XML) или 'namereplace' (замена на escape-последовательности \N{...}). Допустимо также любое другое имя обработчика ошибок, зарегистрированное с помощью codecs.register_error().

newline управляет обработкой окончаний строк. Допустимые значения: None, '', '\n', '\r' и '\r\n'. Поведение описано ниже:

При чтении входных данных из потока, если newline равно None, включается режим универсальных символов новой строки. Строки во входных данных могут заканчиваться на '\n', '\r' или '\r\n'; перед возвратом вызывающей стороне они преобразуются в '\n'. Если newline равно '', режим универсальных символов новой строки включается, но окончания строк возвращаются вызывающей стороне без преобразования. Если newline имеет любое другое допустимое значение, входные строки завершаются только указанной строкой, а окончание строки возвращается вызывающей стороне без преобразования.
При записи выходных данных в поток, если newline равно None, все записываемые символы '\n' преобразуются в системный разделитель строк по умолчанию os.linesep. Если newline равно '' или '\n', преобразование не выполняется. Если newline имеет любое другое допустимое значение, все записываемые символы '\n' преобразуются в указанную строку.

Если line_buffering равно True, вызов flush() подразумевается, когда вызов записи содержит символ новой строки или возврата каретки.

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

Изменено в версии 3.3: Добавлен аргумент write_through.

Изменено в версии 3.3: Теперь кодировка encoding по умолчанию — locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Не изменяйте временно кодировку локали с помощью locale.setlocale(); вместо предпочтительной кодировки пользователя используйте кодировку текущей локали.

Изменено в версии 3.10: Аргумент encoding теперь поддерживает фиктивное имя кодировки "locale".

Примечание

Если базовый необработанный поток работает в неблокирующем режиме, может возникнуть исключение BlockingIOError, если операцию чтения нельзя завершить немедленно.

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.

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

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

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

Добавлено в версии 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.

Статическая типизация

Следующие протоколы можно использовать для аннотирования аргументов функций и методов при выполнении простых операций чтения из потока или записи в него. Для них задан декоратор @typing.runtime_checkable.

class io.Reader[T]

Обобщённый протокол для чтения из файла или другого входного потока. T обычно будет иметь тип str или bytes, но может иметь любой тип данных, считываемых из потока.

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

read()
read(size, /): Считывает данные из входного потока и возвращает их. Если указан size, он должен быть целым числом, и будет считано не более size элементов (байтов/символов).

Например:

def read_it(reader: Reader[str]):
    data = reader.read(11)
    assert isinstance(data, str)

class io.Writer[T]

Обобщённый протокол для записи в файл или другой выходной поток. T обычно будет иметь тип str или bytes, но может иметь любой тип данных, которые можно записать в поток.

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

write(data, /): Записывает data в выходной поток и возвращает количество записанных элементов (байтов/символов).

Например:

def write_binary(writer: Writer[bytes]):
    writer.write(b"Hello world!\n")

Другие протоколы и классы, связанные с вводом-выводом и пригодные для статической проверки типов, см. в разделе ABC и протоколы для работы с вводом-выводом.

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

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

Двоичный ввод-вывод

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