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

Исходный код: 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.

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

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

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

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

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

Смотрите также

Режим Python UTF-8

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

PEP 686

Python 3.15 сделает режим Python UTF-8 режимом по умолчанию.

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

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

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 истинно и 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Иерархия классов

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

Примечание

Абстрактные базовые классы также предоставляют реализации по умолчанию некоторых методов для упрощения реализации конкретных классов потоков. Например, 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

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

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

Изменено в версии 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, возвращаются все байты до конца файла. В противном случае выполняется только один системный вызов. Может быть возвращено меньше байт, чем size, если системный вызов вернул меньше байт, чем size.

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

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

readall()¶

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

readinto(b, /)¶

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

write(b, /)¶

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

class io.BufferedIOBase¶

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

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

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

При чтении максимально возможного количества данных реализация по умолчанию будет использовать 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, /)¶

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

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

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

readinto1(b, /)¶

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

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

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

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

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

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

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

Методы read() (при вызове с положительным аргументом), readinto() и write() этого класса будут выполнять только один системный вызов.

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

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

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

Изменено в версии 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, содержащее все содержимое буфера.

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-like object, b, и возвращает количество записанных байтов. В неблокирующем режиме возбуждается BlockingIOError с установленным BlockingIOError.characters_written, если буфер необходимо сбросить, но необработанный поток блокируется.

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.

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' приводит к замене повреждённых данных управляющей последовательностью с обратной косой чертой. При записи можно использовать 'xmlcharrefreplace' (замена соответствующей ссылкой на символ XML) или 'namereplace' (замена управляющими последовательностями \N{...}). Также допустимо любое другое имя обработки ошибок, зарегистрированное с помощью codecs.register_error().

newline управляет обработкой концов строк. Он может быть равен None, '', '\n', '\r' и '\r\n'. Он работает следующим образом:

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

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

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

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

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

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

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

Примечание

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

Этот метод выполняет неявный сброс (flush) потока перед установкой новых параметров.

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

# Получить содержимое файла — это будет
# '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")

Смотрите ABCs and Protocols for working with I/O для других протоколов и классов, связанных с I/O, которые можно использовать для статической проверки типов.

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

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

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

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

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

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

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

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

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

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

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

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

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

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