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

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

Обзор

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

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

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

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

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

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

Проще всего создать текстовый поток с помощью open(), при необходимости указав кодировку:

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

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

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

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

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

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

Проще всего создать двоичный поток с помощью open(), указав 'b' в строке режима:

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

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

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

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

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

Необработанный ввод-вывод

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

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

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

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

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

Однако многие разработчики забывают указывать кодировку при открытии текстовых файлов в UTF-8 (например, JSON, TOML, Markdown и т. д.), поскольку на большинстве Unix-платформ по умолчанию используется локаль UTF-8. Это приводит к ошибкам, поскольку у большинства пользователей 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". Поддержка encoding="locale" для использования текущей кодировки локали появилась в Python 3.10.

См. также

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

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

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

При чтении максимально возможного объёма реализация по умолчанию использует 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()) лежащего в основе необработанного потока. Вернуть количество прочитанных байт.

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

write(b, /)

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

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

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

Низкоуровневый ввод-вывод файлов

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

Необработанный двоичный поток, представляющий файл уровня ОС, содержащий байты. Наследуется от RawIOBase.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

class io.TextIOBase

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

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

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

errors: Параметр обработки ошибок декодера или кодировщика.

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

buffer: Базовый двоичный буфер (экземпляр BufferedIOBase или 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_through равно True, вызовы write() гарантированно не буферизуются: любые данные, записанные в объект TextIOWrapper, немедленно передаются его базовому двоичному буферу.

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

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

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

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

line_buffering: Включена ли построчная буферизация.

write_through: Передаются ли данные записи немедленно в базовый двоичный буфер.

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

reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)

Перенастраивает этот текстовый поток с новыми значениями параметров encoding, errors, newline, line_buffering и write_through.

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

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

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

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

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

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

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

StringIO, однако, представляет собой нативный контейнер Юникода в памяти и работает примерно так же быстро, как BytesIO.

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

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

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

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

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

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

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