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

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

Обзор¶

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

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

Все потоки внимательно относятся к типу данных, которые вы им передаете. Например, если присвоить объекту 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-like objects и создает объекты bytes. Кодирование, декодирование или перевод на новую строку не выполняются. Эта категория потоков может использоваться для всех видов нетекстовых данных, а также в тех случаях, когда требуется ручное управление обработкой текстовых данных.

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

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

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

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

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

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

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

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

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

API raw stream подробно описан в документации по 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.

См.также

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

Предупреждение о включенном кодировании¶

Добавлено в версии 3.10: Смотрите PEP 597 для получения более подробной информации.

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

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

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

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

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

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

Создает auditing event open с аргументами path, 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.

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

Эта функция выдает 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 и кодировка равна None.

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

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

См.также

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

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

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

Примечание

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

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

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

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

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

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

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

азбука	Наследует	Методы заглушки	Способы и свойства смешивания
`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. Другие bytes-like objects также принимаются в качестве аргументов метода. Классы текстового ввода-вывода работают с str данными.

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

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

IOBase также является контекстным менеджером и, следовательно, поддерживает инструкцию with. В этом примере файл закрывается после завершения набора инструкций 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, /)¶

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

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

readlines(hint=-1, /)¶

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

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

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

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

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

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

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

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

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

tell()¶: Верните текущее положение потока.

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

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

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

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

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

class io.RawIOBase¶

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

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

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

read(size=-1, /)¶

Считывает из объекта байты до размера size и возвращает их. Для удобства, если значение size не указано или равно -1, возвращаются все байты до EOF. В противном случае выполняется только один системный вызов. Может быть возвращено меньше size байт, если вызов операционной системы возвращает меньше size байт.

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

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

readall()¶: Считывает и возвращает все байты из потока до EOF, при необходимости используя несколько вызовов потока.

readinto(b, /)¶: Считывает байты в заранее выделенный, доступный для записи bytes-like object b и возвращает количество прочитанных байт. Например, b может быть bytearray. Если объект находится в неблокирующем режиме и байты недоступны, возвращается None.

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

class io.BufferedIOBase¶

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

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

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

Кроме того, метод read() не имеет реализации по умолчанию, которая зависела бы от readinto().

Типичная реализация BufferedIOBase не должна наследоваться от реализации RawIOBase, а должна завершать ее, как это делают BufferedWriter и BufferedReader.

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

raw¶: Базовый необработанный поток (экземпляр RawIOBase), с которым имеет дело BufferedIOBase. Это не является частью BufferedIOBase API и может отсутствовать в некоторых реализациях.

detach()¶

Отделите базовый необработанный поток от буфера и верните его обратно.

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

Некоторые буферы, такие как BytesIO, не имеют концепции единого необработанного потока, возвращаемого этим методом. Они генерируют UnsupportedOperation.

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

read(size=-1, /)¶

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

Если аргумент положительный, а базовый необработанный поток не является интерактивным, может быть выполнено несколько необработанных операций чтения для удовлетворения количества байт (если только сначала не будет достигнут EOF). Но для интерактивных необработанных потоков будет выдано не более одного необработанного чтения, и короткий результат не означает, что EOF неизбежен.

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

read1(size=-1, /)¶

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

Если размер равен -1 (значение по умолчанию), возвращается произвольное количество байт (больше нуля, если не достигнут EOF).

readinto(b, /)¶

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

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

readinto1(b, /)¶

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

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

write(b, /)¶

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

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

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

Ввод-вывод необработанного файла¶

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

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

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

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

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

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

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

Только что созданный файл имеет значение non-inheritable.

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

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

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

FileIO предоставляет эти атрибуты данных в дополнение к атрибутам из RawIOBase и IOBase:

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

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

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

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

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

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

Необязательный аргумент initial_bytes - это bytes-like object, который содержит исходные данные.

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

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

peek(size=0, /)¶: Возвращает байты из потока без изменения позиции. Для выполнения запроса выполняется не более одного чтения в исходном потоке. Количество возвращаемых байтов может быть меньше или больше запрошенного.

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

read1(size=-1, /)¶: Считывает и возвращает данные размером до байт, используя только один вызов для необработанного потока. Если буферизован хотя бы один байт, возвращаются только буферизованные байты. В противном случае выполняется один вызов для чтения из необработанного потока.

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶

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

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

BufferedRandom способен на все, что могут сделать BufferedReader или BufferedWriter. Кроме того, seek() и tell() гарантированно будут реализованы.

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

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

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

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

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

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

Ввод текста¶

class io.TextIOBase¶

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

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

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

errors¶: Ошибка настройки декодера или кодировщика.

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

buffer¶: Базовый двоичный буфер (экземпляр BufferedIOBase), с которым работает TextIOBase. Это не является частью TextIOBase API и может отсутствовать в некоторых реализациях.

detach()¶

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

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

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

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

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

readline(size=-1, /)¶

Считывать до новой строки или EOF и возвращать единичный str. Если поток уже находится в EOF, возвращается пустая строка.

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

seek(offset, whence=SEEK_SET, /)¶

Измените положение потока на заданное значение offset. Поведение зависит от параметра where from. Значение where from по умолчанию равно SEEK_SET.

SEEK_SET или 0: выполняется поиск с начала потока (по умолчанию); offset должно быть либо числом, возвращаемым TextIOBase.tell(), либо нулем. Любое другое значение offset приводит к неопределенному поведению.
SEEK_CUR или 1: «поиск» в текущей позиции; смещение должно быть равно нулю, что не является операцией (все остальные значения не поддерживаются).
SEEK_END или 2: поиск до конца потока; смещение должно быть равно нулю (все остальные значения не поддерживаются).

Верните новую абсолютную позицию в виде непрозрачного числа.

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

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

write(s, /)¶: Запишите строку s в поток и верните количество записанных символов.

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)¶

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

encoding указывает название кодировки, в которой будет декодироваться или кодироваться поток. По умолчанию используется значение locale.getencoding(). encoding="locale" может использоваться для явного указания кодировки текущего языкового стандарта. Смотрите Кодировка текста для получения дополнительной информации.

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

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

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

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

Если значение 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.

Параметры, которые не указаны, сохраняют текущие настройки, за исключением того, что 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¶: Вспомогательный кодек, который декодирует новые строки для режима universal newlines. Он наследуется от codecs.IncrementalDecoder.

Представление¶

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

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

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

Ввод текста¶

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

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

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

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

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

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

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

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

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

os — Различные интерфейсы операционной системы

time — Временной доступ и конверсии

Вернуться на верх

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

Обзор¶

Ввод текста¶

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

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

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

Предупреждение о включенном кодировании¶

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

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

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

Ввод-вывод необработанного файла¶

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

Ввод текста¶

Представление¶

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

Ввод текста¶

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

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

Python 3.11

Содержание

Дополнительно

Вы здесь:

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

Обзор¶

Ввод текста¶

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

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

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

Предупреждение о включенном кодировании¶

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

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

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

Ввод-вывод необработанного файла¶

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

Ввод текста¶

Представление¶

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

Ввод текста¶

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

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

Python 3.11

Содержание

Дополнительно

Вы здесь:

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