`io.md`

775 строк · 60.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/io.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 15.2. `io` – Основные инструменты для работы с потоками89## 15.2.1. Обзор1011Модуль `io` предоставляет основные средства Python для работы с различными типами ввода-вывода. Существует три основных типа ввода-вывода: *текстовый ввод-вывод*, *двоичный ввод-вывод* и *необработанный ввод-вывод*. Это общие категории, и для каждой из них могут использоваться различные подсистемы хранения. Конкретные объекты, принадлежащие к любой из этих категорий, часто называют *потоками данных*; другой распространённый термин – *объекты, подобные файлам*.1213Независимо от категории, каждый конкретный объект потока также может обладать различными возможностями: он может быть только для чтения, только для записи или для чтения и записи. Он также может поддерживать произвольный доступ (переход вперёд или назад к любому месту) или только последовательный доступ (например, в случае сокета или канала).1415Все потоки внимательны к типу данных, которые им передаются. Например, передача объекта [`str`](https://python-all.ru/3.1/library/functions.html#str) методу `write()` двоичного потока вызовет исключение `TypeError`. То же самое произойдёт при передаче объекта [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) методу `write()` текстового потока.1617### 15.2.1.1. Текстовый ввод-вывод1819Текстовый ввод-вывод ожидает и создаёт объекты [`str`](https://python-all.ru/3.1/library/functions.html#str). Это означает, что когда хранилище данных изначально состоит из байтов (как в случае с файлом), кодирование и декодирование данных выполняется прозрачно, а также выполняется опциональное преобразование символов новой строки, специфичных для платформы.2021Самый простой способ создать текстовый поток – использовать [`open()`](https://python-all.ru/3.1/library/functions.html#open), опционально указав кодировку:2223```python24f = open("myfile.txt", "r", encoding="utf-8")25```2627Текстовые потоки в памяти также доступны как объекты [`StringIO`](https://python-all.ru/3.1/library/io.html#io.StringIO):2829```python30f = io.StringIO("some initial text data")31```3233API текстового потока подробно описан в документации к [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase).3435### 15.2.1.2. Двоичный ввод-вывод3637Двоичный ввод-вывод (также называемый *буферизованным вводом-выводом*) ожидает и создаёт объекты [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes). Никакого кодирования, декодирования или преобразования новых строк не выполняется. Эта категория потоков может использоваться для всех видов нетекстовых данных, а также когда требуется ручное управление обработкой текстовых данных.3839Самый простой способ создать двоичный поток – использовать [`open()`](https://python-all.ru/3.1/library/functions.html#open) с `'b'` в строке режима:4041```python42f = open("myfile.jpg", "rb")43```4445Двоичные потоки в памяти также доступны как объекты [`BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO):4647```python48f = io.BytesIO(b"some initial binary data: \x00\x01")49```5051API двоичных потоков подробно описан в документации [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase).5253Другие модули библиотеки могут предоставлять дополнительные способы создания текстовых или двоичных потоков. Смотрите, например, [`socket.socket.makefile()`](https://python-all.ru/3.1/library/socket.html#socket.socket.makefile).5455### 15.2.1.3. Необработанный ввод-вывод5657Необработанный ввод-вывод (также называемый *небуферизованным вводом-выводом*) обычно используется как низкоуровневый строительный блок для двоичных и текстовых потоков; редко бывает полезно напрямую манипулировать необработанным потоком из пользовательского кода. Тем не менее, можно создать необработанный поток, открыв файл в двоичном режиме с отключённой буферизацией:5859```python60f = open("myfile.jpg", "rb", buffering=0)61```6263API сырых потоков подробно описан в документации [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase).6465## 15.2.2. Интерфейс модуля высокого уровня6667#### `io.DEFAULT_BUFFER_SIZE`6869Целое число, содержащее размер буфера по умолчанию, используемый буферизованными классами ввода-вывода модуля.7071[`open()`](https://python-all.ru/3.1/library/functions.html#open)7273использует blksize файла (получаемый с помощью7475[`os.stat()`](https://python-all.ru/3.1/library/os.html#os.stat)7677), если это возможно.7879#### `io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True)`8081Это псевдоним для встроенной функции8283[`open()`](https://python-all.ru/3.1/library/functions.html#open)8485.8687#### `exception io.BlockingIOError`8889Исключение, возникающее при блокировке неблокирующего потока. Наследует [`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError).9091В дополнение к атрибутам [`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError), [`BlockingIOError`](https://python-all.ru/3.1/library/io.html#io.BlockingIOError) имеет один атрибут:9293#### `characters_written`9495Целое число, содержащее количество символов, записанных в поток до его блокировки.9697#### `exception io.UnsupportedOperation`9899Исключение, наследующее100101[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)102103и104105[`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError)106107, которое возбуждается при вызове неподдерживаемой операции над потоком.108109### 15.2.2.1. Потоки в памяти110111Также можно использовать объект, подобный [`str`](https://python-all.ru/3.1/library/functions.html#str) или [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), в качестве файла как для чтения, так и для записи. Для строк [`StringIO`](https://python-all.ru/3.1/library/io.html#io.StringIO) можно использовать как файл, открытый в текстовом режиме. [`BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO) можно использовать как файл, открытый в двоичном режиме. Оба предоставляют полные возможности чтения и записи с произвольным доступом.112113> **См. также**114>115> **[`sys`](https://python-all.ru/3.1/library/sys.html#module-sys)**116>117> содержит стандартные потоки ввода-вывода:118>119> [`sys.stdin`](https://python-all.ru/3.1/library/sys.html#sys.stdin)120>121> ,122>123> [`sys.stdout`](https://python-all.ru/3.1/library/sys.html#sys.stdout)124>125> и126>127> [`sys.stderr`](https://python-all.ru/3.1/library/sys.html#sys.stderr)128>129> .130131## 15.2.3. Иерархия классов132133Реализация потоков ввода-вывода организована в виде иерархии классов. Сначала [*абстрактные базовые классы*](https://python-all.ru/3.1/glossary.html#term-abstract-base-class) (ABC), которые используются для определения различных категорий потоков, затем конкретные классы, предоставляющие стандартные реализации потоков.134135> > **Примечание**136> >137> > Абстрактные базовые классы также предоставляют реализации некоторых методов по умолчанию, чтобы упростить реализацию конкретных классов потоков. Например, [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase) предоставляет неоптимизированные реализации `readinto()` и `readline()`.138139На вершине иерархии ввода-вывода находится абстрактный базовый класс [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase). Он определяет базовый интерфейс для потока. Однако обратите внимание, что нет разделения между чтением и записью в потоках; реализациям разрешено вызывать [`UnsupportedOperation`](https://python-all.ru/3.1/library/io.html#io.UnsupportedOperation), если они не поддерживают данную операцию.140141Абстрактный базовый класс [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase) расширяет [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase). Он занимается чтением и записью байтов в поток. [`FileIO`](https://python-all.ru/3.1/library/io.html#io.FileIO) является подклассом [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase) и предоставляет интерфейс для файлов в файловой системе машины.142143Абстрактный базовый класс [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase) занимается буферизацией на сыром байтовом потоке ([`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase)). Его подклассы [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter), [`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader) и [`BufferedRWPair`](https://python-all.ru/3.1/library/io.html#io.BufferedRWPair) буферизуют потоки, которые доступны для чтения, записи или для чтения и записи одновременно. [`BufferedRandom`](https://python-all.ru/3.1/library/io.html#io.BufferedRandom) предоставляет буферизованный интерфейс для потоков с произвольным доступом. Ещё один подкласс [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase), [`BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO), представляет собой поток байтов в памяти.144145Абстрактный базовый класс [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase), ещё один подкласс [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase), занимается потоками, байты которых представляют текст, и обрабатывает кодирование и декодирование в строки и из строк. [`TextIOWrapper`](https://python-all.ru/3.1/library/io.html#io.TextIOWrapper), который расширяет его, представляет собой буферизованный текстовый интерфейс к буферизованному сырому потоку ([`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase)). Наконец, [`StringIO`](https://python-all.ru/3.1/library/io.html#io.StringIO) – это поток текста в памяти.146147Имена аргументов не являются частью спецификации, и только аргументы [`open()`](https://python-all.ru/3.1/library/functions.html#open) предназначены для использования в качестве именованных аргументов.148149### 15.2.3.1. Базовые классы ввода-вывода150151#### `class io.IOBase`152153Абстрактный базовый класс для всех классов ввода-вывода, работающий с потоками байтов. Отсутствует открытый конструктор.154155Этот класс предоставляет пустые абстрактные реализации для многих методов, которые производные классы могут выборочно переопределять; реализации по умолчанию представляют файл, который нельзя читать, записывать или позиционировать.156157Хотя [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase) не объявляет `read()`, `readinto()`, или `write()`, поскольку их сигнатуры различаются, реализации и клиенты должны считать эти методы частью интерфейса. Кроме того, реализации могут возбуждать [`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError) при вызове неподдерживаемых операций.158159Базовым типом для двоичных данных, читаемых из файла или записываемых в файл, является [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes). Типы [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray) также принимаются, а в некоторых случаях (например, `readinto`) требуются. Классы текстового ввода-вывода работают с данными типа [`str`](https://python-all.ru/3.1/library/functions.html#str).160161Обратите внимание, что вызов любого метода (даже запросов) на закрытом потоке является неопределённым поведением. Реализации могут возбуждать [`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError) в этом случае.162163IOBase (и его подклассы) поддерживают протокол итерации; это означает, что объект [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase) можно перебирать, получая строки из потока. Строки определяются немного по-разному в зависимости от того, является ли поток двоичным (возвращает байты) или текстовым (возвращает строки символов). См. [`readline()`](https://python-all.ru/3.1/library/io.html#io.IOBase.readline) ниже.164165IOBase также является контекстным менеджером и поэтому поддерживает оператор [`with`](https://python-all.ru/3.1/reference/compound_stmts.html#with). В этом примере *file* закрывается после завершения блока оператора [`with`](https://python-all.ru/3.1/reference/compound_stmts.html#with) – даже если возникло исключение:166167```python168with open('spam.txt', 'w') as file:169    file.write('Spam and eggs!')170```171172[`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase) предоставляет следующие атрибуты данных и методы:173174#### `close()`175176Сбрасывает буфер и закрывает этот поток. Этот метод не делает ничего, если файл уже закрыт. Как только файл закрыт, любая операция с файлом (например, чтение или запись) вызовет [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError).177178Для удобства допускается вызывать этот метод несколько раз; однако эффект будет иметь только первый вызов.179180#### `closed`181182True, если поток закрыт.183184#### `fileno()`185186Возвращает базовый файловый дескриптор (целое число) потока, если он существует. Если объект ввода-вывода не использует файловый дескриптор, возбуждается187188[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)189190.191192#### `flush()`193194Сбрасывает буферы записи потока, если это применимо. Для потоков только для чтения и неблокирующих потоков эта операция ничего не делает.195196#### `isatty()`197198Возвращает199200`True`201202, если поток интерактивный (т.е. подключен к терминалу/tty-устройству).203204#### `readable()`205206Возвращает207208`True`209210, если из потока можно читать. Если False,211212`read()`213214возбудит215216[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)217218.219220#### `readline(limit=-1)`221222Читает и возвращает одну строку из потока. Если указан *limit*, будет прочитано не более *limit* байт.223224Для двоичных файлов признаком конца строки всегда является `b'\n'`; для текстовых файлов через параметр *newlines* функции [`open()`](https://python-all.ru/3.1/library/functions.html#open) можно указать, какие признаки конца строки распознавать.225226#### `readlines(hint=-1)`227228Читает и возвращает список строк из потока. Можно указать229230*hint*231232для ограничения количества читаемых строк: чтение прекратится, когда общий размер (в байтах/символах) всех прочитанных строк превысит233234*hint*235236.237238#### `seek(offset, whence=SEEK_SET)`239240Изменяет позицию в потоке на заданное смещение в байтах *offset*. *offset* интерпретируется относительно позиции, задаваемой параметром *whence*. Допустимые значения *whence*:241242- `SEEK_SET` или `0` – начало потока (по умолчанию); *offset* должен быть нулевым или положительным243- `SEEK_CUR` или `1` – текущая позиция в потоке; *offset* может быть отрицательным244- `SEEK_END` или `2` – конец потока; *offset* обычно отрицательный245246Возвращает новую абсолютную позицию.247248Новое в версии 3.1: Константы `SEEK_*`.249250#### `seekable()`251252Возвращает253254`True`255256, если поток поддерживает произвольный доступ. Если257258`False`259260,261262[`seek()`](https://python-all.ru/3.1/library/io.html#io.IOBase.seek)263264,265266[`tell()`](https://python-all.ru/3.1/library/io.html#io.IOBase.tell)267268и269270[`truncate()`](https://python-all.ru/3.1/library/io.html#io.IOBase.truncate)271272возбудят273274[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)275276.277278#### `tell()`279280Возвращает текущую позицию в потоке.281282#### `truncate(size=None)`283284Изменяет размер потока до указанного285286*size*287288в байтах (или до текущей позиции, если289290*size*291292не указан). Текущая позиция в потоке не изменяется. Это изменение размера может увеличить или уменьшить текущий размер файла. В случае увеличения содержимое новой области файла зависит от платформы (в большинстве систем дополнительные байты заполняются нулями, в Windows они не определены). Возвращается новый размер файла.293294#### `writable()`295296Возвращает297298`True`299300, если поток поддерживает запись. Если301302`False`303304,305306`write()`307308и309310[`truncate()`](https://python-all.ru/3.1/library/io.html#io.IOBase.truncate)311312возбудят313314[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)315316.317318#### `writelines(lines)`319320Записывает список строк в поток. Разделители строк не добавляются, поэтому обычно каждая переданная строка уже содержит разделитель в конце.321322#### `class io.RawIOBase`323324Базовый класс для необработанного бинарного ввода-вывода. Наследует [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase). Открытого конструктора нет.325326Необработанный двоичный ввод-вывод обычно предоставляет низкоуровневый доступ к базовому устройству или API операционной системы и не пытается инкапсулировать его в высокоуровневые примитивы (это оставлено буферизованному и текстовому вводу-выводу, описанным далее на этой странице).327328В дополнение к атрибутам и методам из [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase), RawIOBase предоставляет следующие методы:329330#### `read(n=-1)`331332Читает до *n* байт из объекта и возвращает их. Для удобства, если *n* не указан или равен -1, вызывается [`readall()`](https://python-all.ru/3.1/library/io.html#io.RawIOBase.readall). В противном случае выполняется только один системный вызов. Может быть возвращено меньше *n* байт, если операционная система возвращает меньше *n* байт.333334Если возвращено 0 байт, а *n* не был 0, это означает конец файла. Если объект в неблокирующем режиме и байты недоступны, возвращается `None`.335336#### `readall()`337338Читает и возвращает все байты из потока до EOF, при необходимости выполняя несколько вызовов к потоку.339340#### `readinto(b)`341342Читает до len(b) байт в bytearray343344*b*345346и возвращает количество прочитанных байт. Если объект находится в неблокирующем режиме и байты недоступны, возвращается347348`None`349350.351352#### `write(b)`353354Записывает заданный объект bytes или bytearray,355356*b*357358, в нижележащий необработанный поток данных и возвращает количество записанных байт. Это может быть меньше359360`len(b)`361362, в зависимости от особенностей нижележащего необработанного потока данных, и особенно если он находится в неблокирующем режиме.363364`None`365366возвращается, если необработанный поток данных настроен так, чтобы не блокироваться, и ни один байт не может быть сразу записан в него.367368#### `class io.BufferedIOBase`369370Базовый класс для двоичных потоков, поддерживающих некоторую буферизацию. Он наследует [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase). Открытый конструктор отсутствует.371372Основное отличие от [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase) заключается в том, что методы [`read()`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase.read), [`readinto()`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase.readinto) и [`write()`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase.write) будут пытаться (соответственно) прочитать столько входных данных, сколько запрошено, или потребить все переданные выходные данные, ценой, возможно, более одного системного вызова.373374Кроме того, эти методы могут вызывать [`BlockingIOError`](https://python-all.ru/3.1/library/io.html#io.BlockingIOError), если нижележащий небуферизованный поток находится в неблокирующем режиме и не может принять или отдать достаточно данных; в отличие от их аналогов из [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase), они никогда не вернут `None`.375376Besides, the [`read()`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase.read) method does not have a default implementation that defers to [`readinto()`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase.readinto).377378Типичная реализация [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase) не должна наследовать от реализации [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase), а должна оборачивать её, как это делают [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter) и [`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader).379380[`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase) предоставляет или переопределяет следующие члены в дополнение к членам из [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase):381382#### `raw`383384Нижележащий небуферизованный поток (экземпляр385386[`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase)387388), с которым работает389390[`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase)391392. Это не часть API393394[`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase)395396и может отсутствовать в некоторых реализациях.397398#### `detach()`399400Отделяет базовый сырой поток от буфера и возвращает его.401402После отсоединения сырого потока буфер переходит в нерабочее состояние.403404Некоторые буферы, такие как [`BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO), не имеют понятия единого небуферизованного потока для возврата из этого метода. Они вызывают [`UnsupportedOperation`](https://python-all.ru/3.1/library/io.html#io.UnsupportedOperation).405406Новое в версии 3.1.407408#### `read(n=-1)`409410Читает и возвращает не более *n* байтов. Если аргумент опущен, равен `None` или отрицателен, данные читаются и возвращаются до достижения EOF. Если поток уже находится в конце, возвращается пустой объект bytes.411412Если аргумент положителен, а базовый сырой поток не является интерактивным, может быть выполнено несколько сырых чтений, чтобы обеспечить требуемое количество байт (если только не достигнут EOF). Но для интерактивных сырых потоков будет выполнено не более одного сырого чтения, и короткий результат не означает, что EOF неизбежен.413414[`BlockingIOError`](https://python-all.ru/3.1/library/io.html#io.BlockingIOError) возникает, если нижележащий небуферизованный поток находится в неблокирующем режиме и в данный момент не имеет доступных данных.415416#### `read1(n=-1)`417418Читает и возвращает до419420*n*421422байт, выполняя не более одного вызова метода423424[`read()`](https://python-all.ru/3.1/library/io.html#io.RawIOBase.read)425426нижележащего небуферизованного потока. Это может быть полезно при реализации собственной буферизации поверх объекта427428[`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase)429430.431432#### `readinto(b)`433434Читает до len(b) байтов в bytearray *b* и возвращает количество прочитанных байтов.435436Как и [`read()`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase.read), к нижележащему необработанному потоку может быть выполнено несколько чтений, если только он не является «интерактивным».437438[`BlockingIOError`](https://python-all.ru/3.1/library/io.html#io.BlockingIOError) возникает, если нижележащий небуферизованный поток находится в неблокирующем режиме и в данный момент не имеет доступных данных.439440#### `write(b)`441442Записывает указанный объект bytes или bytearray *b* и возвращает количество записанных байтов (никогда не меньше `len(b)`, так как при ошибке записи будет возбуждено исключение [`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)). В зависимости от конкретной реализации эти байты могут быть немедленно записаны в нижележащий поток или сохранены в буфере для повышения производительности и снижения задержек.443444В неблокирующем режиме возникает [`BlockingIOError`](https://python-all.ru/3.1/library/io.html#io.BlockingIOError), если данные необходимо записать в небуферизованный поток, но он не может принять все данные без блокировки.445446### 15.2.3.2. Сырой файловый ввод-вывод447448#### `class io.FileIO(name, mode='r', closefd=True)`449450[`FileIO`](https://python-all.ru/3.1/library/io.html#io.FileIO) представляет файл на уровне ОС, содержащий байтовые данные. Он реализует интерфейс [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase) (а следовательно, и интерфейс [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase)).451452Параметр *name* может быть одним из двух:453454- строка символов или объект bytes, представляющий путь к открываемому файлу;455- целое число, представляющее номер существующего файлового дескриптора на уровне ОС, к которому будет предоставлять доступ результирующий объект [`⟦/2FileIO`](https://python-all.ru/3.1/library/io.html#io.FileIO).456457Параметр *mode* может быть равен `'r'`, `'w'` или `'a'` для чтения (по умолчанию), записи или дозаписи. Файл будет создан, если он не существует, при открытии на запись или дозапись; при открытии на запись файл будет усечён. Добавление `'+'` к режиму позволяет одновременно читать и писать.458459Методы `read()` (при вызове с положительным аргументом), `readinto()` и `write()` этого класса будут выполнять только один системный вызов.460461В дополнение к атрибутам и методам от [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase) и [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase), [`FileIO`](https://python-all.ru/3.1/library/io.html#io.FileIO) предоставляет следующие атрибуты и методы:462463#### `mode`464465Режим, указанный в конструкторе.466467#### `name`468469Имя файла. Это дескриптор файла, если имя не указано в конструкторе.470471### 15.2.3.3. Буферизированные потоки данных472473Буферизированные потоки ввода-вывода предоставляют интерфейс более высокого уровня к устройству ввода-вывода, чем небуферизированный.474475#### `class io.BytesIO([initial_bytes])`476477Реализация потока, использующая буфер байт в памяти. Наследует [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase).478479Аргумент *initial\_bytes* содержит необязательные начальные данные [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes).480481[`BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO) предоставляет или переопределяет следующие методы в дополнение к методам из [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase) и [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase):482483#### `getvalue()`484485Возвращает объект486487`bytes`488489, содержащий всё содержимое буфера.490491#### `read1()`492493В494495[`BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO)496497это эквивалентно498499`read()`500501.502503#### `class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)`504505Буфер, обеспечивающий доступ более высокого уровня к читаемому последовательному объекту [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase). Наследует [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase). При чтении данных из этого объекта из нижележащего необработанного потока может запрашиваться больший объём данных, которые сохраняются во внутреннем буфере. Затем буферизованные данные могут быть прямо возвращены при последующих чтениях.506507Конструктор создаёт [`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader) для переданного читаемого потока *raw* и *buffer\_size*. Если *buffer\_size* опущен, используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.1/library/io.html#io.DEFAULT_BUFFER_SIZE).508509[`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader) предоставляет или переопределяет следующие методы в дополнение к методам из [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase) и [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase):510511#### `peek([n])`512513Возвращает байты из потока без продвижения позиции. Для выполнения вызова производится не более одного чтения из сырого потока. Количество возвращённых байт может быть меньше или больше запрошенного.514515#### `read([n])`516517Читает и возвращает518519*n*520521байт, или, если522523*n*524525не указан или отрицателен, до EOF или если вызов чтения заблокируется в неблокирующем режиме.526527#### `read1(n)`528529Читает и возвращает до530531*n*532533байт, выполняя только один вызов небуферизованного потока. Если в буфере есть хотя бы один байт, возвращаются только буферизованные байты. В противном случае выполняется один вызов чтения небуферизованного потока.534535#### `class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)`536537Буфер, предоставляющий высокоуровневый доступ к записываемому последовательному объекту [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase). Он наследует [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase). При записи в этот объект данные обычно хранятся во внутреннем буфере. Буфер будет сброшен в нижележащий объект [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase) при различных условиях, в том числе:538539- когда буфер становится слишком мал для всех ожидающих данных;540- при вызове [`flush()`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter.flush);541- при запросе `seek()` (для объектов [`BufferedRandom`](https://python-all.ru/3.1/library/io.html#io.BufferedRandom));542- когда объект [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter) закрывается или уничтожается.543544Конструктор создаёт [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter) для переданного записываемого потока *raw*. Если *buffer\_size* не указан, по умолчанию используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.1/library/io.html#io.DEFAULT_BUFFER_SIZE).545546Третий аргумент, *max\_buffer\_size*, поддерживается, но не используется и устарел.547548[`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter) предоставляет или переопределяет следующие методы в дополнение к методам из [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase) и [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase):549550#### `flush()`551552Принудительно сбрасывает байты, находящиеся в буфере, в необработанный поток. Если необработанный поток блокируется, должно быть возбуждено исключение553554[`BlockingIOError`](https://python-all.ru/3.1/library/io.html#io.BlockingIOError)555556.557558#### `write(b)`559560Записывает объект bytes или bytearray561562*b*563564и возвращает количество записанных байтов. В неблокирующем режиме, если требуется сбросить буфер, но необработанный поток блокируется, возбуждается исключение565566[`BlockingIOError`](https://python-all.ru/3.1/library/io.html#io.BlockingIOError)567568.569570#### `class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)`571572Буферизованный объект ввода-вывода, обеспечивающий комбинированный доступ более высокого уровня к двум последовательным объектам [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase): один для чтения, другой для записи. Он полезен для пар однонаправленных каналов связи (например, каналов). Он наследует [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase).573574*reader* и *writer* – это объекты [`RawIOBase`](https://python-all.ru/3.1/library/io.html#io.RawIOBase), предназначенные соответственно для чтения и записи. Если *buffer\_size* опущен, по умолчанию используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.1/library/io.html#io.DEFAULT_BUFFER_SIZE).575576Четвёртый аргумент, *max\_buffer\_size*, поддерживается, но не используется и устарел.577578[`BufferedRWPair`](https://python-all.ru/3.1/library/io.html#io.BufferedRWPair) реализует все методы [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase), за исключением [`detach()`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase.detach), который возбуждает [`UnsupportedOperation`](https://python-all.ru/3.1/library/io.html#io.UnsupportedOperation).579580#### `class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)`581582Буферизованный интерфейс для потоков с произвольным доступом. Он наследует [`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader) и [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter), а также поддерживает функциональность `seek()` и `tell()`.583584Конструктор создаёт читатель и писатель для позиционируемого необработанного потока, заданного в первом аргументе. Если *buffer\_size* опущен, по умолчанию используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.1/library/io.html#io.DEFAULT_BUFFER_SIZE).585586Третий аргумент, *max\_buffer\_size*, поддерживается, но не используется и устарел.587588[`BufferedRandom`](https://python-all.ru/3.1/library/io.html#io.BufferedRandom) способен на всё, что могут [`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader) или [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter).589590### 15.2.3.4. Текстовый ввод-вывод591592#### `class io.TextIOBase`593594Базовый класс для текстовых потоков. Этот класс предоставляет посимвольный и построчный интерфейс для потокового ввода-вывода. Метод `readinto()` отсутствует, поскольку строки Python неизменяемы. Он наследует [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase). Открытый конструктор отсутствует.595596[`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase) предоставляет или переопределяет следующие атрибуты данных и методы в дополнение к унаследованным от [`IOBase`](https://python-all.ru/3.1/library/io.html#io.IOBase):597598#### `encoding`599600Имя кодировки, используемой для декодирования байтов потока в строки и для кодирования строк в байты.601602#### `errors`603604Настройка обработки ошибок декодера или кодера.605606#### `newlines`607608Строка, кортеж строк или609610`None`611612, указывающие на переведённые на данный момент символы новой строки. В зависимости от реализации и начальных флагов конструктора это может быть недоступно.613614#### `buffer`615616Базовый бинарный буфер (экземпляр617618[`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase)619620), с которым работает621622[`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase)623624. Это не часть API625626[`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase)627628и может отсутствовать в некоторых реализациях.629630#### `detach()`631632Отделяет базовый бинарный буфер от [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase) и возвращает его.633634После отсоединения базового буфера [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase) переходит в неработоспособное состояние.635636Некоторые реализации [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase), например [`StringIO`](https://python-all.ru/3.1/library/io.html#io.StringIO), могут не иметь понятия базового буфера, и вызов этого метода приведёт к возбуждению [`UnsupportedOperation`](https://python-all.ru/3.1/library/io.html#io.UnsupportedOperation).637638Новое в версии 3.1.639640#### `read(n)`641642Читает и возвращает не более643644*n*645646символов из потока в виде одной647648[`str`](https://python-all.ru/3.1/library/functions.html#str)649650. Если651652*n*653654отрицательно или655656`None`657658, читает до конца файла (EOF).659660#### `readline()`661662Читает до символа новой строки или конца файла и возвращает одну строку663664`str`665666. Если поток уже достиг конца файла, возвращается пустая строка.667668#### `write(s)`669670Записывает строку671672*s*673674в поток и возвращает количество записанных символов.675676#### `class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False)`677678Буферизированный текстовый поток поверх бинарного потока [`BufferedIOBase`](https://python-all.ru/3.1/library/io.html#io.BufferedIOBase). Наследует [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase).679680*encoding* задаёт имя кодировки, в которую будет декодироваться или кодироваться поток. По умолчанию используется [`locale.getpreferredencoding()`](https://python-all.ru/3.1/library/locale.html#locale.getpreferredencoding).681682*errors* – необязательная строка, определяющая, как обрабатывать ошибки кодирования и декодирования. Передача `'strict'` вызывает исключение [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError) при ошибке кодирования (значение по умолчанию `None` имеет тот же эффект), а `'ignore'` игнорирует ошибки. (Обратите внимание, что игнорирование ошибок кодирования может привести к потере данных.) `'replace'` вставляет замещающий символ (например, `'?'`) в места неверных данных. При записи можно использовать `'xmlcharrefreplace'` (замена соответствующей XML-ссылкой на символ) или `'backslashreplace'` (замена escape-последовательностями с обратной косой чертой). Допустимо любое другое имя обработки ошибок, зарегистрированное в [`codecs.register_error()`](https://python-all.ru/3.1/library/codecs.html#codecs.register_error).683684*newline* может быть `None`, `''`, `'\n'`, `'\r'` или `'\r\n'`. Он управляет обработкой концов строк. Если он равен `None`, включён универсальный режим концов строк. При включённом режиме на вводе концы строк `'\n'`, `'\r'` или `'\r\n'` преобразуются в `'\n'` перед возвратом вызывающему. И наоборот, на выводе `'\n'` преобразуется в системный разделитель строк по умолчанию [`os.linesep`](https://python-all.ru/3.1/library/os.html#os.linesep). Если *newline* является любым другим допустимым значением, этот символ становится концом строки при чтении файла и возвращается без преобразования. На выводе `'\n'` преобразуется в *newline*.685686Если *line\_buffering* равно `True`, `flush()` подразумевается при вызове write, содержащем символ новой строки.687688[`TextIOWrapper`](https://python-all.ru/3.1/library/io.html#io.TextIOWrapper) предоставляет один атрибут в дополнение к атрибутам [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase) и его родительских классов:689690#### `line_buffering`691692Определяет, включена ли построчная буферизация.693694#### `class io.StringIO(initial_value='', newline=None)`695696Поток в памяти для текстового ввода-вывода.697698Начальное значение буфера (по умолчанию пустая строка) можно задать с помощью *initial\_value*. Аргумент *newline* работает так же, как в [`TextIOWrapper`](https://python-all.ru/3.1/library/io.html#io.TextIOWrapper). По умолчанию перевод строки не выполняется.699700[`StringIO`](https://python-all.ru/3.1/library/io.html#io.StringIO) предоставляет этот метод в дополнение к методам из [`TextIOBase`](https://python-all.ru/3.1/library/io.html#io.TextIOBase) и его родительских классов:701702#### `getvalue()`703704Возвращает705706`str`707708, содержащую полное содержимое буфера в любой момент до вызова метода709710`close()`711712объекта713714[`StringIO`](https://python-all.ru/3.1/library/io.html#io.StringIO)715716.717718Пример использования:719720```python721import io722723output = io.StringIO()724output.write('First line.\n')725print('Second line.', file=output)726727# Извлечь содержимое файла – это будет728# 'Первая строка.729Вторая строка.730'731contents = output.getvalue()732733# Закрыть объект и освободить буфер памяти –734# .getvalue() теперь будет вызывать исключение.735output.close()736```737738#### `class io.IncrementalNewlineDecoder`739740Вспомогательный кодек, декодирующий концы строк для универсального режима концов строк. Он наследует741742[`codecs.IncrementalDecoder`](https://python-all.ru/3.1/library/codecs.html#codecs.IncrementalDecoder)743744.745746## 15.2.4. Дополнительные темы747748Здесь будут рассмотрены несколько дополнительных тем, относящихся к конкретным реализациям ввода-вывода, описанным выше.749750### 15.2.4.1. Производительность751752#### 15.2.4.1.1. Двоичный ввод-вывод753754Читая и записывая только большие блоки данных, даже когда пользователь запрашивает один байт, буферизованный ввод-вывод скрывает любую неэффективность вызова и выполнения небуферизованных процедур ввода-вывода операционной системы. Выигрыш сильно зависит от ОС и типа выполняемого ввода-вывода (например, в некоторых современных ОС, таких как Linux, небуферизованный дисковый ввод-вывод может быть таким же быстрым, как буферизованный). Однако суть в том, что буферизованный ввод-вывод обеспечивает предсказуемую производительность независимо от платформы и нижележащего устройства. Поэтому почти всегда предпочтительнее использовать буферизованный ввод-вывод, а не небуферизованный.755756#### 15.2.4.1.2. Текстовый ввод-вывод757758Текстовый ввод-вывод поверх бинарного хранилища (например, файла) работает значительно медленнее, чем бинарный ввод-вывод через то же хранилище, поскольку требует преобразования из Unicode в бинарные данные с помощью кодека символов. Это может стать заметно при обработке больших объёмов текстовых данных (например, очень больших файлов журналов). Кроме того, `TextIOWrapper.tell()` и `TextIOWrapper.seek()` работают довольно медленно из-за используемого алгоритма восстановления.759760[`StringIO`](https://python-all.ru/3.1/library/io.html#io.StringIO), однако, является собственным контейнером юникода в памяти и будет демонстрировать скорость, аналогичную [`BytesIO`](https://python-all.ru/3.1/library/io.html#io.BytesIO).761762### 15.2.4.2. Многопоточность763764Объекты [`FileIO`](https://python-all.ru/3.1/library/io.html#io.FileIO) потокобезопасны настолько, насколько потокобезопасны системные вызовы (например, `read(2)` в Unix), которые они оборачивают.765766Буферизированные бинарные объекты (экземпляры [`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader), [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter), [`BufferedRandom`](https://python-all.ru/3.1/library/io.html#io.BufferedRandom) и [`BufferedRWPair`](https://python-all.ru/3.1/library/io.html#io.BufferedRWPair)) защищают свои внутренние структуры с помощью блокировки; поэтому их можно безопасно вызывать из нескольких потоков одновременно.767768Объекты [`TextIOWrapper`](https://python-all.ru/3.1/library/io.html#io.TextIOWrapper) не являются потокобезопасными.769770### 15.2.4.3. Реентерабельность771772Буферизованные бинарные объекты (экземпляры [`BufferedReader`](https://python-all.ru/3.1/library/io.html#io.BufferedReader), [`BufferedWriter`](https://python-all.ru/3.1/library/io.html#io.BufferedWriter), [`BufferedRandom`](https://python-all.ru/3.1/library/io.html#io.BufferedRandom) и [`BufferedRWPair`](https://python-all.ru/3.1/library/io.html#io.BufferedRWPair)) не являются реентерабельными. Хотя повторные вызовы в обычных ситуациях не возникают, они могут появиться, если выполнять ввод-вывод в обработчике [`signal`](https://python-all.ru/3.1/library/signal.html#module-signal). Если попытаться повторно войти в буферизованный объект, когда к нему уже идёт обращение *из того же потока*, то возбуждается [`RuntimeError`](https://python-all.ru/3.1/library/exceptions.html#RuntimeError).773774Сказанное выше неявно распространяется и на текстовые файлы, поскольку функция [`open()`](https://python-all.ru/3.1/library/functions.html#open) помещает буферизованный объект внутрь [`TextIOWrapper`](https://python-all.ru/3.1/library/io.html#io.TextIOWrapper). Это касается и стандартных потоков, а значит, затрагивает и встроенную функцию [`print()`](https://python-all.ru/3.1/library/functions.html#print).775