Содержание страницы

`io` – основные инструменты для работы с потоками данных¶io – Core tools for working with streams

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

Обзор¶Overview

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

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

Все потоки данных строго следят за типом передаваемых им данных. Например, передача объекта str методу write() двоичного потока вызовет TypeError. То же самое произойдёт при передаче объекта bytes методу write() текстового потока.

Изменено в версии 3.3: Операции, которые раньше вызывали IOError, теперь вызывают OSError, поскольку IOError теперь является псевдонимом OSError.

Текстовый ввод-вывод¶Text I/O

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

Самый простой способ создать текстовый поток – использовать open(), при необходимости указав кодировку:

f = open("myfile.txt", "r", encoding="utf-8")

Текстовые потоки в памяти также доступны в виде объектов StringIO:

f = io.StringIO("some initial text data")

Примечание

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

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

Двоичный ввод-вывод¶Binary I/O

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

Самый простой способ создать двоичный поток – использовать open() с 'b' в строке режима:

f = open("myfile.jpg", "rb")

Двоичные потоки в памяти также доступны в виде объектов BytesIO:

f = io.BytesIO(b"some initial binary data: \x00\x01")

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

Другие библиотечные модули могут предоставлять дополнительные способы создания текстовых или двоичных потоков. См., например, socket.socket.makefile().

Необработанный ввод-вывод¶Raw I/O

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

f = open("myfile.jpg", "rb", buffering=0)

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

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

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

Кодировка текста¶Text Encoding

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

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

# Может не работать в Windows, если в файле есть символы, не входящие в ASCII.
with open("README.md") as f:
    long_description = f.read()

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

См. также

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

Опциональное предупреждение EncodingWarning¶Opt-in 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.

Интерфейс модуля высокого уровня¶High-level Module Interface

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

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

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

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

io.open_code(path)¶

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

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

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

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

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

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

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

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

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

В этом примере EncodingWarning выдается для вызывающего read_text().

См. Кодировка текста для получения дополнительной информации.

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

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

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

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

См. также

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

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

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

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

Базовые классы ввода-вывода¶I/O Base Classes

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, возвращаются все байты до EOF.

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

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

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

readall()¶

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

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

readinto(b, /)¶

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

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

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

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

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

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 или отрицателен, читает максимально возможное количество.

Fewer bytes may be returned than requested. An empty bytes object is returned if the stream is already at EOF. More than one read may be made and calls may be retried if specific errors are encountered, see os.read() and PEP 475 for more details. Less than size bytes being returned does not imply that EOF is imminent.

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

Примечание

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

read1(size=-1, /)¶: Read and return up to size bytes, calling readinto() which may retry if EINTR is encountered per PEP 475. If size is -1 or not provided, the implementation will choose an arbitrary value for size.

Примечание

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

readinto(b, /)¶

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

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

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

readinto1(b, /)¶

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

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

write(b, /)¶

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

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

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

Сырой файловый ввод-вывод¶Raw File I/O

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

Сырой двоичный поток, представляющий файл на уровне ОС, содержащий байтовые данные. Он наследует от RawIOBase и реализует его низкоуровневый дизайн доступа. Это означает, что write() не гарантирует запись всех байт, а read() может прочитать меньше байт, чем запрошено, даже если в нижележащем файле может быть больше данных. Чтобы получить поведение «записать всё» и «прочитать минимум», используйте двоичный ввод-вывод.

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

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

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

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

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

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

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

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

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

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

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

mode¶: Режим, указанный в конструкторе.

name¶: Имя файла. Это дескриптор файла, если имя не указано в конструкторе.

Буферизированные потоки¶Buffered Streams

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

class io.BytesIO(initial_bytes=b'')¶

Двоичный поток, использующий байтовый буфер в памяти. Он наследуется от BufferedIOBase. Буфер отбрасывается при вызове метода close().

Необязательный аргумент initial_bytes – это байтоподобный объект, содержащий начальные данные.

Методы можно использовать из нескольких потоков без внешней блокировки в сборках со свободной многопоточностью.

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

getbuffer()¶

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

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

Примечание

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

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

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

peek(size=0, /)¶

Возвращает копию буфера от текущей позиции и далее, не сдвигая позицию.

Если size меньше единицы или опущен, возвращается не более DEFAULT_BUFFER_SIZE байт. В противном случае возвращается не более size байт. По достижении конца файла возвращается пустой объект bytes.

Добавлено в версии 3.16.0a0 (не выпущено).

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 для заданного записываемого сырого потока. Если buffer_size не указан, по умолчанию используется DEFAULT_BUFFER_SIZE.

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

flush()¶: Принудительно передает байты, находящиеся в буфере, в сырой поток. Если сырой поток блокируется, должно быть возбуждено исключение BlockingIOError.

write(b, /)¶: Записывает байтоподобный объект, 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 не пытается синхронизировать доступ к своим базовым сырым потокам. Не следует передавать ему один и тот же объект в качестве читателя и писателя; вместо этого используйте BufferedRandom.

Текстовый ввод-вывод¶Text I/O

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, читает до конца файла.

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

errors – необязательная строка, которая задаёт, как обрабатывать ошибки кодирования и декодирования. Передайте 'strict', чтобы возбудить исключение ValueError при ошибке кодирования (значение по умолчанию None имеет тот же эффект), или 'ignore', чтобы игнорировать ошибки. (Обратите внимание, что игнорирование ошибок кодирования может привести к потере данных.) 'replace' приводит к вставке замещающего маркера (например, '?') в местах с некорректными данными. 'backslashreplace' заменяет некорректные данные escape-последовательностью с обратной косой чертой. При записи можно использовать '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 содержит символ новой строки или возврата каретки.

Если 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.

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

# Извлечь содержимое файла – это будет
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# Закрыть объект и освободить буфер памяти –
# .getvalue() теперь будет вызывать исключение.
output.close()

class io.IncrementalNewlineDecoder¶: Вспомогательный кодек, который декодирует символы новой строки для режима universal newlines. Он наследуется от codecs.IncrementalDecoder.

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

Следующие протоколы можно использовать для аннотирования аргументов функций и методов для простых операций чтения или записи потоков. Они декорированы с помощью @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 и протоколы для работы с I/O для других протоколов и классов, связанных с вводом-выводом, которые можно использовать для статической проверки типов.

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

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

Двоичный ввод-вывод¶Binary I/O

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

Текстовый ввод-вывод¶Text I/O

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

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

Многопоточность¶Multi-threading

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

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

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

Повторный вход¶Reentrancy

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

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

io – основные инструменты для работы с потоками данных¶io – Core tools for working with streams

Обзор¶Overview

Текстовый ввод-вывод¶Text I/O

Двоичный ввод-вывод¶Binary I/O

Необработанный ввод-вывод¶Raw I/O

Кодировка текста¶Text Encoding

Опциональное предупреждение EncodingWarning¶Opt-in EncodingWarning

Интерфейс модуля высокого уровня¶High-level Module Interface

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

Базовые классы ввода-вывода¶I/O Base Classes

Сырой файловый ввод-вывод¶Raw File I/O

Буферизированные потоки¶Buffered Streams

Текстовый ввод-вывод¶Text I/O

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

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

Двоичный ввод-вывод¶Binary I/O

Текстовый ввод-вывод¶Text I/O

Многопоточность¶Multi-threading

Повторный вход¶Reentrancy

`io` – основные инструменты для работы с потоками данных¶io – Core tools for working with streams