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

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

Модуль io предоставляет интерфейсы Python для работы с потоками. Встроенная функция open() определена в этом модуле.

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

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

BufferedIOBase занимается буферизацией на необработанном байтовом потоке (RawIOBase). Его подклассы: BufferedWriter, BufferedReader и BufferedRWPair буферизуют потоки, которые доступны для чтения, записи и для чтения и записи одновременно. BufferedRandom предоставляет буферизованный интерфейс для потоков с произвольным доступом. BytesIO – это простой поток байтов в памяти.

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

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

Интерфейс модуля¶Module Interface

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

io.open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])¶

Открывает file и возвращает поток. Если файл не может быть открыт, возникает IOError.

file – это либо строка, задающая имя (и путь, если файл не находится в текущей рабочей директории) открываемого файла, либо файловый дескриптор открываемого файла. (Если задан файловый дескриптор, например, из os.fdopen(), он закрывается при закрытии возвращаемого объекта ввода-вывода, если только closefd не установлен в False.)

mode – необязательная строка, определяющая режим, в котором открывается файл. По умолчанию используется 'r', что означает открытие для чтения в текстовом режиме. Другие распространённые значения: 'w' для записи (при этом файл усекается, если он уже существует) и 'a' для добавления (что на некоторых системах Unix означает, что все операции записи добавляются в конец файла независимо от текущей позиции). В текстовом режиме, если encoding не указана, используемая кодировка зависит от платформы. (Для чтения и записи сырых байтов используйте двоичный режим и оставьте encoding неуказанным.) Доступные режимы:

Символ	Значение
`'r'`	открытие для чтения (по умолчанию)
`'w'`	открытие для записи, с предварительным усечением файла
`'a'`	открытие для записи, дозапись в конец файла, если он существует
`'b'`	двоичный режим
`'t'`	текстовый режим (по умолчанию)
`'+'`	открывает дисковый файл для обновления (чтения и записи)
`'U'`	Режим универсального перевода строк (для обратной совместимости; не следует использовать в новом коде).

Режим по умолчанию – 'rt' (открытие для чтения текста). Для бинарного произвольного доступа режим 'w+b' открывает и усекает файл до 0 байт, а 'r+b' открывает файл без усечения.

Python различает файлы, открытые в двоичном и текстовом режимах, даже если базовая операционная система этого не делает. Файлы, открытые в двоичном режиме (включая 'b' в аргументе mode), возвращают содержимое в виде объектов bytes без какого-либо декодирования. В текстовом режиме (по умолчанию, или когда 't' включен в аргументе mode) содержимое файла возвращается в виде строк, при этом байты сначала декодируются с использованием платформозависимой кодировки или указанной encoding, если она задана.

buffering – необязательное целое число, используемое для установки политики буферизации. По умолчанию включена полная буферизация. Передайте 0, чтобы отключить буферизацию (разрешено только в двоичном режиме), 1 – для построчной буферизации и целое число > 1 – для полной буферизации.

encoding – это имя кодировки, используемой для декодирования или кодирования файла. Её следует использовать только в текстовом режиме. Кодировка по умолчанию зависит от платформы, но можно использовать любую кодировку, поддерживаемую Python. Смотрите модуль codecs для списка поддерживаемых кодировок.

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

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

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

Если closefd равен False и был передан файловый дескриптор, а не имя файла, базовый файловый дескриптор останется открытым при закрытии файла. Если передано имя файла, closefd не действует, но должно быть равно True (значение по умолчанию).

Тип файлового объекта, возвращаемого функцией open(), зависит от режима. Когда open() используется для открытия файла в текстовом режиме ('w', 'r', 'wt', 'rt' и т.д.), она возвращает TextIOWrapper. При использовании для открытия файла в двоичном режиме возвращаемый класс различается: в двоичном режиме чтения он возвращает BufferedReader; в режимах двоичной записи и двоичного добавления – BufferedWriter, а в режиме чтения/записи – BufferedRandom.

Также можно использовать строку или bytearray в качестве файла как для чтения, так и для записи. Для строк StringIO можно использовать как файл, открытый в текстовом режиме, а для bytearray – BytesIO как файл, открытый в двоичном режиме.

exception io.BlockingIOError¶

Исключение, возникающее при блокировке неблокирующего потока. Наследует IOError.

В дополнение к атрибутам IOError, BlockingIOError имеет один атрибут:

characters_written¶: Целое число, содержащее количество символов, записанных в поток до его блокировки.

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

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

class io.IOBase¶

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

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

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

Базовым типом для двоичных данных, читаемых из файла или записываемых в файл, является bytes. Типы bytearray также принимаются, а в некоторых случаях (например, readinto) требуются. Классы текстового ввода-вывода работают с данными типа str.

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

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

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

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

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

close()¶: Сбрасывает буферы и закрывает этот поток. Этот метод не действует, если файл уже закрыт. После закрытия файла любая операция с файлом (например, чтение или запись) вызовет IOError. Внутренний файловый дескриптор не закрывается, если closefd было равно False.

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

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

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

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

readable()¶: Возвращает True, если из потока можно читать. Если False, read() возбудит IOError.

readline([limit])¶

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

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

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

seek(offset[, whence])¶

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

0 – начало потока (по умолчанию); offset должен быть нулевым или положительным
1 – текущая позиция в потоке; offset может быть отрицательным
2 – конец потока; offset обычно отрицательный

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

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

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

truncate([size])¶: Усекает файл до не более чем size байт. size по умолчанию равна текущей позиции в файле, возвращаемой tell().

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

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

class io.RawIOBase¶

Базовый класс для необработанного бинарного ввода-вывода. Наследует IOBase. Открытого конструктора нет.

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

read([n])¶: Читает и возвращает все байты из потока до EOF, или, если указано n, до n байт. Выполняется только один системный вызов. Пустой объект bytes возвращается при EOF; None возвращается, если объект настроен не блокироваться и нет данных для чтения.

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

readinto(b)¶: Читает до len(b) байтов в bytearray b и возвращает количество прочитанных байтов.

write(b)¶: Записывает переданный объект bytes или bytearray, b, в нижележащий небуферизованный поток и возвращает количество записанных байт (оно никогда не меньше len(b), так как в случае неудачи записи будет возбуждено IOError).

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

class io.FileIO(name[, mode])¶

FileIO представляет файл, содержащий байтовые данные. Он реализует интерфейс RawIOBase (а значит, и интерфейс IOBase тоже).

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

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

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

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

read([n])¶: Читает и возвращает не более n байт. Выполняется только один системный вызов, поэтому возможно, что возвращается меньше данных, чем запрошено. Используйте len() для возвращённого объекта bytes, чтобы узнать, сколько байт было получено. (В неблокирующем режиме None возвращается, когда нет доступных данных.)

readall()¶: Читает и возвращает всё содержимое файла в виде одного объекта bytes. В неблокирующем режиме возвращается столько, сколько сразу доступно. Если достигнут EOF, возвращается b''.

write(b)¶: Записывает объект bytes или bytearray, b, в файл и возвращает количество реально записанных байт. Выполняется только один системный вызов, поэтому возможно, что записана только часть данных.

Обратите внимание, что унаследованный метод readinto() не следует использовать для объектов FileIO.

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

class io.BufferedIOBase¶

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

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

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

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

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

read([n])¶

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

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

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

readinto(b)¶

Читает до len(b) байтов в bytearray b и возвращает количество прочитанных байтов.

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

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

write(b)¶

Записывает переданный объект bytes или bytearray, b, в нижележащий сырой поток и возвращает количество записанных байт (не меньше len(b), так как при сбое записи будет возбуждено IOError).

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

class io.BytesIO([initial_bytes])¶

Реализация потока, использующая буфер байт в памяти. Наследует BufferedIOBase.

Аргумент initial_bytes – необязательный исходный bytearray.

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

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

read1()¶: В BytesIO это эквивалентно read().

truncate([size])¶: Усекает буфер до размера не более size байт. size по умолчанию равен текущей позиции в потоке, возвращаемой tell().

class io.BufferedReader(raw[, buffer_size])¶

Буфер для читаемого последовательного объекта RawIOBase. Он наследует BufferedIOBase.

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

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

peek([n])¶: Возвращает 1 байт (или n, если указано) из буфера без продвижения позиции. Для удовлетворения вызова выполняется только одно чтение из сырого потока. Количество возвращённых байт может быть меньше запрошенного, так как возвращается не более всех байт буфера от текущей позиции до конца.

read([n])¶: Читает и возвращает n байт, или, если n не указан или отрицателен, до EOF или если вызов чтения заблокируется в неблокирующем режиме.

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

class io.BufferedWriter(raw[, buffer_size[, max_buffer_size]])¶

Буфер для записываемого последовательного объекта RawIO. Он наследует BufferedIOBase.

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

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

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

write(b)¶: Записывает объект bytes или bytearray, b, в сырой поток и возвращает количество записанных байт. BlockingIOError возбуждается, когда сырой поток блокируется.

class io.BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])¶

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

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

BufferedRWPair реализует все методы BufferedIOBase.

class io.BufferedRandom(raw[, buffer_size[, max_buffer_size]])¶

Буферизированный интерфейс для потоков с произвольным доступом. Он наследует BufferedReader и BufferedWriter.

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

BufferedRandom способен на всё, что могут BufferedReader или BufferedWriter.

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

class io.TextIOBase¶

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

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

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

newlines¶: Строка, кортеж строк или None, указывающий на переведённые к настоящему моменту символы новой строки.

read(n)¶: Читает не более n символов из потока и возвращает их в виде одной строки str. Если n отрицательно или None, чтение выполняется до конца файла.

readline()¶: Читает до символа новой строки или конца файла и возвращает одну строку str. Если поток уже достиг конца файла, возвращается пустая строка.

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

class io.TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])¶

Буферизированный текстовый поток поверх raw-потока BufferedIOBase, buffer. Он наследует TextIOBase.

encoding задаёт имя кодировки, в которую будет декодироваться или кодироваться поток. По умолчанию используется locale.getpreferredencoding().

newline может принимать значения None, '', '\n', '\r', или '\r\n'. Он управляет обработкой концов строк. Если он равен None, включается универсальный режим новых строк (universal newlines). В этом режиме при вводе концы строк '\n', '\r' или '\r\n' преобразуются в '\n' перед возвратом вызывающей стороне. Напротив, при выводе '\n' преобразуется в системный разделитель строк по умолчанию, os.linesep. Если newline имеет любое другое допустимое значение, то при чтении файла этот символ становится концом строки и возвращается без преобразования. При выводе '\n' преобразуется в newline.

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

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

errors¶: Настройка обработки ошибок кодирования и декодирования.

line_buffering¶: Определяет, включена ли построчная буферизация.

class io.StringIO([initial_value[, encoding[, errors[, newline]]]])¶

Поток в памяти для текста. Он наследует TextIOWrapper.

Создаёт новый поток StringIO с начальным значением, кодировкой, обработкой ошибок и настройкой символов новой строки. Подробнее см. конструктор TextIOWrapper.

StringIO предоставляет следующий метод в дополнение к методам TextIOWrapper и его родительских классов:

getvalue()¶: Возвращает str, содержащую полное содержимое буфера в любой момент до вызова метода close() объекта StringIO.

Пример использования:

import io

output = io.StringIO()
output.write('First line.\n')
print('Second line.', file=output)

# Извлечь содержимое файла – это будет
# 'Первая строка.
Вторая строка.
'
contents = output.getvalue()

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

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