`io.md`

735 строк · 85.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/library/io.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`io`](https://python-all.ru/3.11/library/io.html#module-io) – основные инструменты для работы с потоками данных89**Исходный код:** [Lib/io.py](https://python-all.ru/src/3.11/Lib/io.py)1011---1213## Обзор1415Модуль [`io`](https://python-all.ru/3.11/library/io.html#module-io) предоставляет основные средства Python для работы с различными типами ввода-вывода. Существует три основных типа ввода-вывода: *текстовый ввод-вывод*, *двоичный ввод-вывод* и *необработанный ввод-вывод*. Это общие категории, и для каждой из них могут использоваться различные хранилища. Конкретный объект, относящийся к любой из этих категорий, называется [файловым объектом](https://python-all.ru/3.11/glossary.html#term-file-object). Другие распространённые термины – *поток данных* и *объект, подобный файлу*.1617Независимо от категории, каждый конкретный потоковый объект также обладает различными возможностями: он может быть только для чтения, только для записи или для чтения и записи. Он может также допускать произвольный доступ (перемещение вперёд или назад к любому месту) или только последовательный доступ (например, в случае сокета или канала).1819Все потоки данных строго следят за типом передаваемых им данных. Например, передача объекта [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) методу `write()` двоичного потока вызовет [`TypeError`](https://python-all.ru/3.11/library/exceptions.html#TypeError). То же самое произойдёт при передаче объекта [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes) методу `write()` текстового потока.2021Изменено в версии 3.3: Операции, которые раньше вызывали [`IOError`](https://python-all.ru/3.11/library/exceptions.html#IOError), теперь вызывают [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError), поскольку [`IOError`](https://python-all.ru/3.11/library/exceptions.html#IOError) теперь является псевдонимом [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError).2223### Текстовый ввод-вывод2425Текстовый ввод-вывод ожидает и возвращает объекты [`str`](https://python-all.ru/3.11/library/stdtypes.html#str). Это означает, что всякий раз, когда хранилище изначально состоит из байтов (например, в случае файла), кодирование и декодирование данных выполняется прозрачно, а также выполняется необязательное преобразование символов новой строки, специфичных для платформы.2627Самый простой способ создать текстовый поток – использовать [`open()`](https://python-all.ru/3.11/library/functions.html#open), при необходимости указав кодировку:2829```python30f = open("myfile.txt", "r", encoding="utf-8")31```3233Текстовые потоки в памяти также доступны в виде объектов [`StringIO`](https://python-all.ru/3.11/library/io.html#io.StringIO):3435```python36f = io.StringIO("some initial text data")37```3839API текстовых потоков подробно описан в документации [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase).4041### Двоичный ввод-вывод4243Двоичный ввод-вывод (также называемый *буферизованным вводом-выводом*) ожидает [байтоподобные объекты](https://python-all.ru/3.11/glossary.html#term-bytes-like-object) и возвращает объекты [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes). Кодирование, декодирование или преобразование символов новой строки не выполняется. Эта категория потоков может использоваться для всех видов нетекстовых данных, а также когда требуется ручной контроль над обработкой текстовых данных.4445Самый простой способ создать двоичный поток – использовать [`open()`](https://python-all.ru/3.11/library/functions.html#open) с `'b'` в строке режима:4647```python48f = open("myfile.jpg", "rb")49```5051Двоичные потоки в памяти также доступны в виде объектов [`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO):5253```python54f = io.BytesIO(b"some initial binary data: \x00\x01")55```5657API двоичных потоков подробно описан в документации [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase).5859Другие библиотечные модули могут предоставлять дополнительные способы создания текстовых или двоичных потоков. См., например, [`socket.socket.makefile()`](https://python-all.ru/3.11/library/socket.html#socket.socket.makefile).6061### Необработанный ввод-вывод6263Необработанный ввод-вывод (также называемый *небуферизованным вводом-выводом*) обычно используется как низкоуровневый строительный блок для двоичных и текстовых потоков; редко бывает полезно напрямую манипулировать необработанным потоком из пользовательского кода. Тем не менее, можно создать необработанный поток, открыв файл в двоичном режиме с отключённой буферизацией:6465```python66f = open("myfile.jpg", "rb", buffering=0)67```6869API необработанных потоков подробно описан в документации [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase).7071## Кодировка текста7273Кодировка по умолчанию для [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper) и [`open()`](https://python-all.ru/3.11/library/functions.html#open) зависит от локали ([`locale.getencoding()`](https://python-all.ru/3.11/library/locale.html#locale.getencoding)).7475Однако многие разработчики забывают указывать кодировку при открытии текстовых файлов, закодированных в UTF-8 (например, JSON, TOML, Markdown и т.д.), поскольку большинство платформ Unix по умолчанию используют локаль UTF-8. Это приводит к ошибкам, потому что кодировка локали не является UTF-8 для большинства пользователей Windows. Например:7677```python78# Может не работать в Windows, если в файле есть символы, не входящие в ASCII.79with open("README.md") as f:80    long_description = f.read()81```8283Соответственно, настоятельно рекомендуется явно указывать кодировку при открытии текстовых файлов. Если вы хотите использовать UTF-8, передайте `encoding="utf-8"`. Для использования текущей кодировки локали `encoding="locale"` поддерживается начиная с Python 3.10.8485> **См. также**86>87> **[Режим UTF-8 Python](https://python-all.ru/3.11/library/os.html#utf8-mode)**88>89> Режим UTF-8 Python можно использовать для изменения кодировки по умолчанию на UTF-8 вместо кодировки, зависящей от локали.90>91> **[**PEP 686**](https://python-all.ru/3.11/library/io.html)**92>93> Python 3.15 сделает [режим UTF-8 Python](https://python-all.ru/3.11/library/os.html#utf8-mode) режимом по умолчанию.9495### Опциональное предупреждение EncodingWarning9697Новое в версии 3.10: См. [**PEP 597**](https://python-all.ru/3.11/library/io.html) для получения дополнительных сведений.9899Чтобы узнать, где используется кодировка локали по умолчанию, можно включить параметр командной строки [`-X warn_default_encoding`](https://python-all.ru/3.11/using/cmdline.html#cmdoption-X) или установить переменную окружения [`PYTHONWARNDEFAULTENCODING`](https://python-all.ru/3.11/using/cmdline.html#envvar-PYTHONWARNDEFAULTENCODING), что вызовет [`EncodingWarning`](https://python-all.ru/3.11/library/exceptions.html#EncodingWarning) при использовании кодировки по умолчанию.100101Если вы предоставляете API, который использует [`open()`](https://python-all.ru/3.11/library/functions.html#open) или [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper) и передаёт `encoding=None` в качестве параметра, вы можете использовать [`text_encoding()`](https://python-all.ru/3.11/library/io.html#io.text_encoding), чтобы вызывающие API выдавали [`EncodingWarning`](https://python-all.ru/3.11/library/exceptions.html#EncodingWarning), если они не передают `encoding`. Однако пожалуйста, рассмотрите возможность использования UTF-8 по умолчанию (т.е. `encoding="utf-8"`) для новых API.102103## Интерфейс модуля высокого уровня104105#### `io.DEFAULT_BUFFER_SIZE`106107Целое число, содержащее размер буфера по умолчанию, используемый классами буферизованного ввода-вывода модуля. [`open()`](https://python-all.ru/3.11/library/functions.html#open) использует blksize файла (получаемый с помощью [`os.stat()`](https://python-all.ru/3.11/library/os.html#os.stat)), если это возможно.108109#### `io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)`110111Это псевдоним для встроенной функции [`open()`](https://python-all.ru/3.11/library/functions.html#open).112113Эта функция вызывает [событие аудита](https://python-all.ru/3.11/library/sys.html#auditing) `open` с аргументами *path*, *mode* и *flags*. Аргументы *mode* и *flags* могут быть изменены или определены из исходного вызова.114115#### `io.open_code(path)`116117Открывает указанный файл в режиме `'rb'`. Эту функцию следует использовать, когда требуется обрабатывать содержимое как исполняемый код.118119*path* должен быть [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) и абсолютным путём.120121Поведение этой функции может быть переопределено более ранним вызовом [`PyFile_SetOpenCodeHook()`](https://python-all.ru/3.11/c-api/file.html#c.PyFile_SetOpenCodeHook). Однако, при условии, что *path* является [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) и абсолютным путём, `open_code(path)` всегда должна вести себя так же, как `open(path, 'rb')`. Переопределение поведения предназначено для дополнительной проверки или предварительной обработки файла.122123Новое в версии 3.8.124125#### `io.text_encoding(encoding, stacklevel=2, /)`126127Это вспомогательная функция для вызываемых объектов, которые используют [`open()`](https://python-all.ru/3.11/library/functions.html#open) или [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper) и имеют параметр `encoding=None`.128129Эта функция возвращает *encoding*, если он не равен `None`. В противном случае она возвращает `"locale"` или `"utf-8"` в зависимости от [режима UTF-8](https://python-all.ru/3.11/library/os.html#utf8-mode).130131Эта функция выдает [`EncodingWarning`](https://python-all.ru/3.11/library/exceptions.html#EncodingWarning), если [`sys.flags.warn_default_encoding`](https://python-all.ru/3.11/library/sys.html#sys.flags) истинно и *encoding* равен `None`. *stacklevel* указывает, где выдается предупреждение. Например:132133```python134def read_text(path, encoding=None):135    encoding = io.text_encoding(encoding)  # stacklevel=2136    with open(path, encoding) as f:137        return f.read()138```139140В этом примере [`EncodingWarning`](https://python-all.ru/3.11/library/exceptions.html#EncodingWarning) выдается для вызывающего `read_text()`.141142См. [Кодировка текста](https://python-all.ru/3.11/library/io.html#io-text-encoding) для получения дополнительной информации.143144Новое в версии 3.10.145146Изменено в версии 3.11: [`text_encoding()`](https://python-all.ru/3.11/library/io.html#io.text_encoding) возвращает "utf-8", когда включен режим UTF-8 и *encoding* равен `None`.147148#### `exception io.BlockingIOError`149150Это псевдоним для встроенного исключения [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError).151152#### `exception io.UnsupportedOperation`153154Исключение, наследующее [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError) и [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError), которое вызывается, когда неподдерживаемая операция вызывается для потока.155156> **См. также**157>158> **[`sys`](https://python-all.ru/3.11/library/sys.html#module-sys)**159>160> содержит стандартные потоки ввода-вывода: [`sys.stdin`](https://python-all.ru/3.11/library/sys.html#sys.stdin), [`sys.stdout`](https://python-all.ru/3.11/library/sys.html#sys.stdout), и [`sys.stderr`](https://python-all.ru/3.11/library/sys.html#sys.stderr).161162## Иерархия классов163164Реализация потоков ввода-вывода организована в виде иерархии классов. Сначала [абстрактные базовые классы](https://python-all.ru/3.11/glossary.html#term-abstract-base-class) (ABC), которые используются для определения различных категорий потоков, затем конкретные классы, предоставляющие стандартные реализации потоков.165166> **Примечание**167>168> Абстрактные базовые классы также предоставляют реализации по умолчанию некоторых методов, чтобы помочь реализации конкретных классов потоков. Например, [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) предоставляет неоптимизированные реализации `readinto()` и `readline()`.169170На вершине иерархии ввода-вывода находится абстрактный базовый класс [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase). Он определяет базовый интерфейс потока. Однако обратите внимание, что нет разделения между чтением и записью в потоки; реализации могут вызывать [`UnsupportedOperation`](https://python-all.ru/3.11/library/io.html#io.UnsupportedOperation), если они не поддерживают данную операцию.171172ABC [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) расширяет [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase). Он занимается чтением и записью байтов в поток. [`FileIO`](https://python-all.ru/3.11/library/io.html#io.FileIO) является подклассом [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase), чтобы предоставить интерфейс к файлам в файловой системе машины.173174ABC [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) расширяет [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase). Он занимается буферизацией сырого двоичного потока ([`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase)). Его подклассы, [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter), [`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader) и [`BufferedRWPair`](https://python-all.ru/3.11/library/io.html#io.BufferedRWPair), буферизуют сырые двоичные потоки, которые доступны для записи, для чтения и для чтения и записи соответственно. [`BufferedRandom`](https://python-all.ru/3.11/library/io.html#io.BufferedRandom) предоставляет буферизованный интерфейс для потоков с произвольным доступом. Другой подкласс [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase), [`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO), является потоком байтов в памяти.175176ABC [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) расширяет [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase). Он занимается потоками, байты которых представляют текст, и обрабатывает кодирование и декодирование в строки и обратно. [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper), который расширяет [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase), является буферизованным текстовым интерфейсом к буферизованному сырому потоку ([`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase)). Наконец, [`StringIO`](https://python-all.ru/3.11/library/io.html#io.StringIO) – это поток текста в памяти.177178Имена аргументов не являются частью спецификации, и только аргументы [`open()`](https://python-all.ru/3.11/library/functions.html#open) предназначены для использования в качестве именованных аргументов.179180В следующей таблице приведены абстрактные базовые классы, предоставляемые модулем [`io`](https://python-all.ru/3.11/library/io.html#module-io):181182| ABC | Наследует | Методы-заглушки | Методы-примеси и свойства |183| --- | --- | --- | --- |184| [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) |  | `fileno`, `seek` и `truncate` | `close`, `closed`, `__enter__`, `__exit__`, `flush`, `isatty`, `__iter__`, `__next__`, `readable`, `readline`, `readlines`, `seekable`, `tell`, `writable` и `writelines` |185| [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) | [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) | `readinto` и `write` | Наследуемые методы [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase), `read`, и `readall` |186| [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) | [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) | `detach`, `read`, `read1`, и `write` | Наследуемые методы [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase), `readinto`, и `readinto1` |187| [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) | [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) | `detach`, `read`, `readline`, и `write` | Наследуемые методы [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase), `encoding`, `errors`, и `newlines` |188189### Базовые классы ввода-вывода190191#### `class io.IOBase`192193Абстрактный базовый класс для всех классов ввода-вывода.194195Этот класс предоставляет пустые абстрактные реализации для многих методов, которые производные классы могут выборочно переопределять; реализации по умолчанию представляют файл, который нельзя читать, записывать или позиционировать.196197Хотя [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) не объявляет `read()` или `write()`, поскольку их сигнатуры различаются, реализации и клиенты должны считать эти методы частью интерфейса. Кроме того, реализации могут возбуждать [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError) (или [`UnsupportedOperation`](https://python-all.ru/3.11/library/io.html#io.UnsupportedOperation)), когда вызываются неподдерживаемые ими операции.198199Базовый тип, используемый для двоичных данных, читаемых из файла или записываемых в файл, – это [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes). Другие [байтоподобные объекты](https://python-all.ru/3.11/glossary.html#term-bytes-like-object) также принимаются в качестве аргументов методов. Классы текстового ввода-вывода работают с данными [`str`](https://python-all.ru/3.11/library/stdtypes.html#str).200201Обратите внимание, что вызов любого метода (даже запросов) для закрытого потока является неопределённым. В этом случае реализации могут возбудить [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError).202203[`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) (и его подклассы) поддерживает протокол итератора, то есть объект [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) можно перебирать, получая строки из потока. Строки определяются немного по-разному в зависимости от того, является ли поток двоичным (возвращает байты) или текстовым (возвращает строки символов). См. [`readline()`](https://python-all.ru/3.11/library/io.html#io.IOBase.readline) ниже.204205[`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) также является контекстным менеджером и поэтому поддерживает инструкцию [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with). В этом примере *file* закрывается после завершения блока инструкции `with` – даже если возникло исключение:206207```python208with open('spam.txt', 'w') as file:209    file.write('Spam and eggs!')210```211212[`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) предоставляет следующие атрибуты данных и методы:213214#### `close()`215216Сбрасывает буферы и закрывает этот поток. Этот метод не оказывает эффекта, если файл уже закрыт. После закрытия файла любая операция с файлом (например, чтение или запись) возбудит [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError).217218Для удобства допускается вызывать этот метод несколько раз; однако эффект будет иметь только первый вызов.219220#### `closed`221222`True`, если поток закрыт.223224#### `fileno()`225226Возвращает базовый файловый дескриптор (целое число) потока, если он существует. Если объект ввода-вывода не использует файловый дескриптор, возбуждается [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError).227228#### `flush()`229230Сбрасывает буферы записи потока, если это применимо. Для потоков только для чтения и неблокирующих потоков эта операция ничего не делает.231232#### `isatty()`233234Возвращает `True`, если поток данных является интерактивным (т.е. подключён к терминальному/tty-устройству).235236#### `readable()`237238Возвращает `True`, если из потока можно читать. Если `False`, `read()` вызовет исключение [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError).239240#### `readline(size=-1, /)`241242Читает и возвращает одну строку из потока. Если указан *size*, будет прочитано не более *size* байт.243244Окончанием строки для бинарных файлов всегда является `b'\n'`; для текстовых файлов аргумент *newline* функции [`open()`](https://python-all.ru/3.11/library/functions.html#open) позволяет выбрать распознаваемые окончания строк.245246#### `readlines(hint=-1, /)`247248Читает и возвращает список строк из потока. Можно указать *hint* для ограничения количества читаемых строк: чтение прекратится, когда общий размер (в байтах/символах) всех прочитанных строк превысит *hint*.249250Значения *hint*, равные `0` или меньше, а также `None`, рассматриваются как отсутствие подсказки.251252Обратите внимание, что по файловым объектам уже можно итерироваться с помощью `for line in file: ...` без вызова `file.readlines()`.253254#### `seek(offset, whence=os.SEEK_SET, /)`255256Изменяет позицию в потоке на заданное смещение *offset* в байтах, интерпретируемое относительно позиции, указанной параметром *whence*, и возвращает новую абсолютную позицию. Возможные значения для *whence*:257258- [`os.SEEK_SET`](https://python-all.ru/3.11/library/os.html#os.SEEK_SET) или `0` – начало потока (по умолчанию); *offset* должно быть нулевым или положительным259- [`os.SEEK_CUR`](https://python-all.ru/3.11/library/os.html#os.SEEK_CUR) или `1` – текущая позиция в потоке; *offset* может быть отрицательным260- [`os.SEEK_END`](https://python-all.ru/3.11/library/os.html#os.SEEK_END) или `2` – конец потока; *offset* обычно отрицателен261262Новое в версии 3.1: Константы `SEEK_*`.263264Новое в версии 3.3: Некоторые операционные системы могут поддерживать дополнительные значения, например [`os.SEEK_HOLE`](https://python-all.ru/3.11/library/os.html#os.SEEK_HOLE) или [`os.SEEK_DATA`](https://python-all.ru/3.11/library/os.html#os.SEEK_DATA). Допустимые значения для файла могут зависеть от того, открыт ли он в текстовом или двоичном режиме.265266#### `seekable()`267268Возвращает `True`, если поток поддерживает произвольный доступ. Если `False`, [`seek()`](https://python-all.ru/3.11/library/io.html#io.IOBase.seek), [`tell()`](https://python-all.ru/3.11/library/io.html#io.IOBase.tell) и [`truncate()`](https://python-all.ru/3.11/library/io.html#io.IOBase.truncate) вызовут исключение [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError).269270#### `tell()`271272Возвращает текущую позицию в потоке.273274#### `truncate(size=None, /)`275276Изменяет размер потока до указанного *size* в байтах (или до текущей позиции, если *size* не указан). Текущая позиция в потоке не меняется. Такое изменение может увеличить или уменьшить текущий размер файла. При увеличении содержимое новой области файла зависит от платформы (в большинстве систем дополнительные байты заполняются нулями). Возвращается новый размер файла.277278Изменено в версии 3.5: В Windows при расширении файлы теперь заполняются нулями.279280#### `writable()`281282Возвращает `True`, если поток поддерживает запись. Если `False`, `write()` и [`truncate()`](https://python-all.ru/3.11/library/io.html#io.IOBase.truncate) вызовут исключение [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError).283284#### `writelines(lines, /)`285286Записывает список строк в поток. Разделители строк не добавляются, поэтому обычно каждая переданная строка уже содержит разделитель в конце.287288#### `__del__()`289290Подготавливает объект к уничтожению. [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase) предоставляет реализацию этого метода по умолчанию, которая вызывает метод [`close()`](https://python-all.ru/3.11/library/io.html#io.IOBase.close) экземпляра.291292#### `class io.RawIOBase`293294Базовый класс для необработанных двоичных потоков. Наследует от [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase).295296Сырые бинарные потоки обычно предоставляют низкоуровневый доступ к базовому устройству ОС или API и не пытаются инкапсулировать его в высокоуровневые примитивы (эта функциональность реализована на более высоком уровне в буферизованных бинарных потоках и текстовых потоках, описанных далее на этой странице).297298[`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) предоставляет эти методы в дополнение к методам из [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):299300#### `read(size=-1, /)`301302Читает из объекта до *size* байт и возвращает их. Для удобства, если *size* не указан или равен -1, возвращаются все байты до конца файла. В противном случае выполняется только один системный вызов. Может быть возвращено меньше *size* байт, если системный вызов вернул меньше *size* байт.303304Если возвращается 0 байт, и *size* не было 0, это означает конец файла. Если объект находится в неблокирующем режиме и байты недоступны, возвращается `None`.305306Реализация по умолчанию делегирует [`readall()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.readall) и [`readinto()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.readinto).307308#### `readall()`309310Читает и возвращает все байты из потока до EOF, при необходимости выполняя несколько вызовов к потоку.311312#### `readinto(b, /)`313314Читает байты в предварительно выделенный, доступный для записи [объект, подобный байтам](https://python-all.ru/3.11/glossary.html#term-bytes-like-object) *b*, и возвращает количество прочитанных байт. Например, *b* может быть [`bytearray`](https://python-all.ru/3.11/library/stdtypes.html#bytearray). Если объект находится в неблокирующем режиме и байты недоступны, возвращается `None`.315316#### `write(b, /)`317318Записывает заданный [bytes-like object](https://python-all.ru/3.11/glossary.html#term-bytes-like-object), *b*, в базовый сырой поток и возвращает количество записанных байт. Это количество может быть меньше длины *b* в байтах в зависимости от особенностей базового сырого потока, особенно если он находится в неблокирующем режиме. `None` возвращается, если сырой поток настроен не блокироваться и ни один байт не может быть сразу записан. Вызывающий код может освободить или изменить *b* после возврата этого метода, поэтому реализация должна обращаться к *b* только во время вызова метода.319320#### `class io.BufferedIOBase`321322Базовый класс для бинарных потоков, поддерживающих некоторую буферизацию. Он наследуется от [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase).323324Основное отличие от [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) заключается в том, что методы [`read()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.read), [`readinto()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.readinto) и [`write()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.write) будут пытаться (соответственно) прочитать столько входных данных, сколько запрошено, или потребить все переданные выходные данные, ценой, возможно, более одного системного вызова.325326Кроме того, эти методы могут вызывать [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError), если базовый небуферизованный поток находится в неблокирующем режиме и не может принять или отдать достаточно данных; в отличие от своих аналогов из [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase), они никогда не вернут `None`.327328Кроме того, метод [`read()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.read) не имеет реализации по умолчанию, которая делегирует [`readinto()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.readinto).329330Типичная реализация [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) не должна наследовать от реализации [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase), а должна оборачивать её, как это делают [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter) и [`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader).331332[`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) предоставляет или переопределяет следующие атрибуты данных и методы в дополнение к атрибутам и методам из [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):333334#### `raw`335336Базовый сырой поток (экземпляр [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase)), с которым работает [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase). Это не является частью API [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) и может отсутствовать в некоторых реализациях.337338#### `detach()`339340Отделяет базовый сырой поток от буфера и возвращает его.341342После отсоединения сырого потока буфер переходит в нерабочее состояние.343344Некоторые буферы, такие как [`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO), не имеют концепции одного сырого потока для возврата из этого метода. Они вызывают [`UnsupportedOperation`](https://python-all.ru/3.11/library/io.html#io.UnsupportedOperation).345346Новое в версии 3.1.347348#### `read(size=-1, /)`349350Читает и возвращает до *size* байт. Если аргумент опущен, равен `None` или отрицателен, данные читаются и возвращаются до достижения EOF. Если поток уже в конце файла, возвращается пустой объект [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes).351352Если аргумент положителен, а базовый сырой поток не является интерактивным, может быть выполнено несколько сырых чтений, чтобы обеспечить требуемое количество байт (если только не достигнут EOF). Но для интерактивных сырых потоков будет выполнено не более одного сырого чтения, и короткий результат не означает, что EOF неизбежен.353354Исключение [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError) возбуждается, если базовый сырой поток находится в неблокирующем режиме и в данный момент не содержит данных.355356#### `read1(size=-1, /)`357358Читает и возвращает до *size* байт, выполняя не более одного вызова метода [`read()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.read) (или [`readinto()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.readinto)) базового сырого потока. Это может быть полезно при реализации собственной буферизации поверх объекта [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase).359360Если *size* равен `-1` (значение по умолчанию), возвращается произвольное количество байт (больше нуля, если только не достигнут EOF).361362#### `readinto(b, /)`363364Читает байты в предварительно выделенный, доступный для записи [байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object) *b* и возвращает количество прочитанных байт. Например, *b* может быть [`bytearray`](https://python-all.ru/3.11/library/stdtypes.html#bytearray).365366Как и [`read()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.read), может быть выполнено несколько чтений из нижележащего сырого потока, если только последний не является интерактивным.367368Исключение [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError) возбуждается, если нижележащий сырой поток находится в неблокирующем режиме и в данный момент не имеет доступных данных.369370#### `readinto1(b, /)`371372Читает байты в предварительно выделенный, доступный для записи [байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object) *b*, используя не более одного вызова метода [`read()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.read) (или [`readinto()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.readinto)) нижележащего сырого потока. Возвращает количество прочитанных байт.373374Исключение [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError) возбуждается, если нижележащий сырой поток находится в неблокирующем режиме и в данный момент не имеет доступных данных.375376Новое в версии 3.5.377378#### `write(b, /)`379380Записывает данный [байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object), *b*, и возвращает количество записанных байт (всегда равное длине *b* в байтах, поскольку если запись завершается неудачей, возбуждается [`OSError`](https://python-all.ru/3.11/library/exceptions.html#OSError)). В зависимости от реализации, эти байты могут быть сразу записаны в нижележащий поток или сохранены в буфере по соображениям производительности и задержки.381382В неблокирующем режиме возбуждается [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError), если данные необходимо записать в сырой поток, но он не может принять все данные без блокировки.383384Вызывающий код может освободить или изменить *b* после возврата из этого метода, поэтому реализация должна обращаться к *b* только во время вызова метода.385386### Сырой файловый ввод-вывод387388#### `class io.FileIO(name, mode='r', closefd=True, opener=None)`389390Сырой двоичный поток, представляющий файл на уровне ОС, содержащий байтовые данные. Он наследуется от [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase).391392Параметр *name* может быть одним из двух:393394- строкой или объектом [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), представляющим путь к файлу, который будет открыт. В этом случае closefd должен быть `True` (по умолчанию), иначе будет возбуждена ошибка.395- целым числом, представляющим номер существующего файлового дескриптора уровня ОС, к которому результирующий объект [`FileIO`](https://python-all.ru/3.11/library/io.html#io.FileIO) предоставит доступ. Когда объект FileIO будет закрыт, этот fd также будет закрыт, если только *closefd* не установлен в `False`.396397Параметр *mode* может быть `'r'`, `'w'`, `'x'` или `'a'` для чтения (по умолчанию), записи, исключительного создания или добавления. Файл будет создан, если он не существует при открытии для записи или добавления; он будет усечён при открытии для записи. [`FileExistsError`](https://python-all.ru/3.11/library/exceptions.html#FileExistsError) будет возбуждено, если он уже существует при открытии для создания. Открытие файла для создания подразумевает запись, поэтому этот режим ведёт себя аналогично `'w'`. Добавьте `'+'` к режиму, чтобы разрешить одновременное чтение и запись.398399Методы [`read()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.read) (при вызове с положительным аргументом), [`readinto()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.readinto) и [`write()`](https://python-all.ru/3.11/library/io.html#io.RawIOBase.write) этого класса выполняют только один системный вызов.400401Можно использовать пользовательский открыватель, передав вызываемый объект как *opener*. Нижележащий файловый дескриптор для объекта файла затем получается вызовом *opener* с (*name*, *flags*). *opener* должен вернуть открытый файловый дескриптор (передача [`os.open`](https://python-all.ru/3.11/library/os.html#os.open) в качестве *opener* приводит к функциональности, аналогичной передаче `None`).402403Созданный файл является [ненаследуемым](https://python-all.ru/3.11/library/os.html#fd-inheritance).404405Смотрите встроенную функцию [`open()`](https://python-all.ru/3.11/library/functions.html#open) для примеров использования параметра *opener*.406407Изменено в версии 3.3: Добавлен параметр *opener*. Добавлен режим `'x'`.408409Изменено в версии 3.4: Файл теперь не наследуется.410411[`FileIO`](https://python-all.ru/3.11/library/io.html#io.FileIO) предоставляет следующие атрибуты данных в дополнение к тем, что от [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) и [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):412413#### `mode`414415Режим, указанный в конструкторе.416417#### `name`418419Имя файла. Это дескриптор файла, если имя не указано в конструкторе.420421### Буферизированные потоки422423Буферизированные потоки ввода-вывода предоставляют интерфейс более высокого уровня к устройству ввода-вывода, чем небуферизированный.424425#### `class io.BytesIO(initial_bytes=b'')`426427Двоичный поток, использующий байтовый буфер в памяти. Он наследуется от [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase). Буфер отбрасывается при вызове метода [`close()`](https://python-all.ru/3.11/library/io.html#io.IOBase.close).428429Необязательный аргумент *initial\_bytes* – это [байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object), содержащий начальные данные.430431[`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO) предоставляет или переопределяет эти методы в дополнение к методам из [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) и [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):432433#### `getbuffer()`434435Возвращает доступное для чтения и записи представление содержимого буфера без его копирования. Изменение этого представления также прозрачно обновляет содержимое буфера:436437```python438>>> b = io.BytesIO(b"abcdef")439>>> view = b.getbuffer()440>>> view[2:4] = b"56"441>>> b.getvalue()442b'ab56ef'443```444445> **Примечание**446>447> Пока существует представление, объект [`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO) нельзя изменить в размере или закрыть.448449Новое в версии 3.2.450451#### `getvalue()`452453Возвращает [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), содержащий всё содержимое буфера.454455#### `read1(size=-1, /)`456457В [`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO) это то же самое, что и [`read()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.read).458459Изменено в версии 3.7: Аргумент *size* теперь необязателен.460461#### `readinto1(b, /)`462463В [`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO) это то же самое, что и [`readinto()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.readinto).464465Новое в версии 3.5.466467#### `class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)`468469Буферизированный двоичный поток, предоставляющий доступ более высокого уровня к читаемому небуферизированному двоичному потоку [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) без поддержки позиционирования. Он наследуется от [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase).470471При чтении данных из этого объекта может быть запрошен больший объём данных из нижележащего небуферизированного потока, и эти данные сохраняются во внутреннем буфере. Затем буферизированные данные могут быть возвращены непосредственно при последующих чтениях.472473Конструктор создаёт [`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader) для заданного читаемого потока *raw* и *buffer\_size*. Если *buffer\_size* не указан, используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.11/library/io.html#io.DEFAULT_BUFFER_SIZE).474475[`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader) предоставляет или переопределяет следующие методы в дополнение к методам из [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) и [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):476477#### `peek(size=0, /)`478479Возвращает байты из потока без продвижения позиции. Для выполнения вызова производится не более одного чтения из сырого потока. Количество возвращённых байт может быть меньше или больше запрошенного.480481#### `read(size=-1, /)`482483Читает и возвращает *size* байт, или, если *size* не задан или отрицателен, до достижения EOF или пока вызов чтения не заблокируется в неблокирующем режиме.484485#### `read1(size=-1, /)`486487Читает и возвращает до *size* байт, выполняя только один вызов к сырому потоку. Если хотя бы один байт уже находится в буфере, возвращаются только буферизованные байты. В противном случае выполняется один вызов чтения сырого потока.488489Изменено в версии 3.7: Аргумент *size* теперь необязателен.490491#### `class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)`492493Буферизированный двоичный поток, предоставляющий доступ более высокого уровня к записываемому небуферизированному двоичному потоку [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) без поддержки позиционирования. Он наследуется от [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase).494495При записи в этот объект данные обычно помещаются во внутренний буфер. Буфер будет сброшен в нижележащий объект [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) при различных условиях, в том числе:496497- когда буфер становится слишком мал для всех ожидающих данных;498- когда вызывается [`flush()`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter.flush);499- когда запрашивается [`seek()`](https://python-all.ru/3.11/library/io.html#io.IOBase.seek) (для объектов [`BufferedRandom`](https://python-all.ru/3.11/library/io.html#io.BufferedRandom));500- когда объект [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter) закрывается или уничтожается.501502Конструктор создает [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter) для заданного записываемого *сырого* потока. Если *buffer\_size* не указан, по умолчанию используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.11/library/io.html#io.DEFAULT_BUFFER_SIZE).503504[`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter) предоставляет или переопределяет следующие методы в дополнение к методам из [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase) и [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):505506#### `flush()`507508Принудительно передает байты, находящиеся в буфере, в сырой поток. Если сырой поток блокируется, должно быть возбуждено исключение [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError).509510#### `write(b, /)`511512Записывает [байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object), *b*, и возвращает количество записанных байт. В неблокирующем режиме возбуждается [`BlockingIOError`](https://python-all.ru/3.11/library/exceptions.html#BlockingIOError), если необходимо сбросить буфер, но сырой поток блокируется.513514#### `class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)`515516Буферизованный двоичный поток, предоставляющий доступ более высокого уровня к позиционируемому [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) необработанному двоичному потоку. Он наследует от [`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader) и [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter).517518Конструктор создает читатель и писатель для сырого потока с произвольным доступом, заданного в первом аргументе. Если *buffer\_size* опущен, по умолчанию используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.11/library/io.html#io.DEFAULT_BUFFER_SIZE).519520[`BufferedRandom`](https://python-all.ru/3.11/library/io.html#io.BufferedRandom) способен на все, что могут [`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader) или [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter). Кроме того, гарантируется реализация [`seek()`](https://python-all.ru/3.11/library/io.html#io.IOBase.seek) и [`tell()`](https://python-all.ru/3.11/library/io.html#io.IOBase.tell).521522#### `class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)`523524Буферизированный двоичный поток, обеспечивающий высокоуровневый доступ к двум не поддерживающим позиционирование сырым двоичным потокам [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase) – один читаемый, другой записываемый. Он наследуется от [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase).525526*reader* и *writer* – это объекты [`RawIOBase`](https://python-all.ru/3.11/library/io.html#io.RawIOBase), которые являются читаемыми и записываемыми соответственно. Если *buffer\_size* опущен, по умолчанию используется [`DEFAULT_BUFFER_SIZE`](https://python-all.ru/3.11/library/io.html#io.DEFAULT_BUFFER_SIZE).527528[`BufferedRWPair`](https://python-all.ru/3.11/library/io.html#io.BufferedRWPair) реализует все методы [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase), за исключением [`detach()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.detach), который возбуждает [`UnsupportedOperation`](https://python-all.ru/3.11/library/io.html#io.UnsupportedOperation).529530> **Предупреждение**531>532> [`BufferedRWPair`](https://python-all.ru/3.11/library/io.html#io.BufferedRWPair) не пытается синхронизировать доступ к своим базовым сырым потокам. Не следует передавать ему один и тот же объект в качестве читателя и писателя; вместо этого используйте [`BufferedRandom`](https://python-all.ru/3.11/library/io.html#io.BufferedRandom).533534### Текстовый ввод-вывод535536#### `class io.TextIOBase`537538Базовый класс для текстовых потоков. Этот класс предоставляет символьный и построчный интерфейс для потокового ввода-вывода. Он наследуется от [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase).539540[`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) предоставляет или переопределяет следующие атрибуты данных и методы в дополнение к атрибутам и методам из [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):541542#### `encoding`543544Имя кодировки, используемой для декодирования байтов потока в строки и для кодирования строк в байты.545546#### `errors`547548Настройка обработки ошибок декодера или кодера.549550#### `newlines`551552Строка, кортеж строк или `None`, указывающие, какие символы новой строки были преобразованы на данный момент. В зависимости от реализации и исходных флагов конструктора это может быть недоступно.553554#### `buffer`555556Базовый двоичный буфер (экземпляр [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase)), с которым работает [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase). Это не часть [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) API и может отсутствовать в некоторых реализациях.557558#### `detach()`559560Отделяет базовый двоичный буфер от [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) и возвращает его.561562После отсоединения базового буфера [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) непригоден для использования.563564Некоторые реализации [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase), например [`StringIO`](https://python-all.ru/3.11/library/io.html#io.StringIO), могут не иметь понятия базового буфера, и вызов этого метода вызовет [`UnsupportedOperation`](https://python-all.ru/3.11/library/io.html#io.UnsupportedOperation).565566Новое в версии 3.1.567568#### `read(size=-1, /)`569570Читает не более *size* символов из потока и возвращает их в виде [`str`](https://python-all.ru/3.11/library/stdtypes.html#str). Если *size* отрицательно или `None`, читает до конца файла.571572#### `readline(size=-1, /)`573574Читает до символа новой строки или конца файла и возвращает одну [`str`](https://python-all.ru/3.11/library/stdtypes.html#str). Если поток уже находится в конце файла, возвращается пустая строка.575576Если указан *size*, будет прочитано не более *size* символов.577578#### `seek(offset, whence=SEEK_SET, /)`579580Изменяет позицию в потоке на заданное значение *offset*. Поведение зависит от параметра *whence*. Значением по умолчанию для *whence* является `SEEK_SET`.581582- `SEEK_SET` или `0`: поиск от начала потока (по умолчанию); *offset* должен быть либо числом, возвращённым [`TextIOBase.tell()`](https://python-all.ru/3.11/library/io.html#io.TextIOBase.tell), либо нулём. Любое другое значение *offset* приводит к неопределённому поведению.583- `SEEK_CUR` или `1`: «поиск» в текущую позицию; *offset* должен быть нулём, что является пустой операцией (все остальные значения не поддерживаются).584- `SEEK_END` или `2`: поиск в конец потока; *offset* должен быть нулём (все остальные значения не поддерживаются).585586Возвращает новую абсолютную позицию в виде непрозрачного числа.587588Новое в версии 3.1: Константы `SEEK_*`.589590#### `tell()`591592Возвращает текущую позицию в потоке в виде непрозрачного числа. Обычно это число не соответствует количеству байт в базовом двоичном хранилище.593594#### `write(s, /)`595596Записывает строку *s* в поток и возвращает количество записанных символов.597598#### `class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)`599600Буферизированный текстовый поток, предоставляющий доступ более высокого уровня к буферизированному двоичному потоку [`BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase). Наследует от [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase).601602*encoding* задаёт название кодировки, с помощью которой поток будет декодироваться или кодироваться. По умолчанию используется [`locale.getencoding()`](https://python-all.ru/3.11/library/locale.html#locale.getencoding). `encoding="locale"` можно использовать для явного указания кодировки текущей локали. Подробнее см. [Кодировка текста](https://python-all.ru/3.11/library/io.html#io-text-encoding).603604*errors* – необязательная строка, которая задаёт, как обрабатывать ошибки кодирования и декодирования. Передайте `'strict'`, чтобы возбудить исключение [`ValueError`](https://python-all.ru/3.11/library/exceptions.html#ValueError) при ошибке кодирования (значение по умолчанию `None` имеет тот же эффект), или `'ignore'`, чтобы игнорировать ошибки. (Обратите внимание, что игнорирование ошибок кодирования может привести к потере данных.) `'replace'` приводит к вставке замещающего маркера (например, `'?'`) в местах с некорректными данными. `'backslashreplace'` заменяет некорректные данные escape-последовательностью с обратной косой чертой. При записи можно использовать `'xmlcharrefreplace'` (замена на соответствующий XML-символьный объект) или `'namereplace'` (замена на escape-последовательности `\N{...}`). Любое другое имя обработчика ошибок, зарегистрированное с помощью [`codecs.register_error()`](https://python-all.ru/3.11/library/codecs.html#codecs.register_error), также допустимо.605606Параметр *newline* управляет обработкой концов строк. Он может принимать значения `None`, `''`, `'\n'`, `'\r'` и `'\r\n'`. Работает следующим образом:607608- При чтении входных данных из потока, если *newline* равен `None`, включается режим [универсальных новых строк](https://python-all.ru/3.11/glossary.html#term-universal-newlines). Строки во входных данных могут заканчиваться на `'\n'`, `'\r'` или `'\r\n'`, и они преобразуются в `'\n'` перед возвратом вызывающей стороне. Если *newline* равен `''`, режим универсальных новых строк включается, но концы строк возвращаются вызывающей стороне без преобразования. Если *newline* имеет любое другое допустимое значение, входные строки завершаются только указанной строкой, и конец строки возвращается вызывающей стороне без преобразования.609- При записи в поток, если *newline* равен `None`, все символы `'\n'` преобразуются в системный разделитель строк по умолчанию [`os.linesep`](https://python-all.ru/3.11/library/os.html#os.linesep). Если *newline* равен `''` или `'\n'`, преобразование не выполняется. Если *newline* равен любому другому допустимому значению, все символы `'\n'` преобразуются в заданную строку.610611Если *line\_buffering* равен `True`, то [`flush()`](https://python-all.ru/3.11/library/io.html#io.IOBase.flush) подразумевается, когда вызов write содержит символ новой строки или возврата каретки.612613Если *write\_through* равен `True`, вызовы [`write()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.write) гарантированно не буферизируются: любые данные, записанные в объект [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper), немедленно передаются его базовому двоичному *буферу*.614615Изменено в версии 3.3: Добавлен аргумент *write\_through*.616617Изменено в версии 3.3: Значение *encoding* по умолчанию теперь равно `locale.getpreferredencoding(False)` вместо `locale.getpreferredencoding()`. Не изменяйте временно кодировку локали с помощью [`locale.setlocale()`](https://python-all.ru/3.11/library/locale.html#locale.setlocale), используйте текущую кодировку локали вместо предпочитаемой пользователем.618619Изменено в версии 3.10: Аргумент *encoding* теперь поддерживает фиктивное имя кодировки `"locale"`.620621[`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper) предоставляет следующие атрибуты данных и методы в дополнение к тем, что есть у [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) и [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):622623#### `line_buffering`624625Определяет, включена ли построчная буферизация.626627#### `write_through`628629Определяет, передаются ли данные записи немедленно в нижележащий двоичный буфер.630631Добавлено в версии 3.7.632633#### `reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)`634635Перенастраивает этот текстовый поток, используя новые значения для *encoding*, *errors*, *newline*, *line\_buffering* и *write\_through*.636637Неуказанные параметры сохраняют текущие настройки, за исключением того, что `errors='strict'` используется, когда *encoding* указан, а *errors* не указан.638639Невозможно изменить кодировку или newline, если из потока уже были прочитаны некоторые данные. Однако изменить кодировку после записи можно.640641Этот метод выполняет неявный сброс потока перед установкой новых параметров.642643Добавлено в версии 3.7.644645Изменено в версии 3.11: Метод поддерживает опцию `encoding="locale"`.646647#### `seek(cookie, whence=os.SEEK_SET, /)`648649Устанавливает позицию потока. Возвращает новую позицию потока в виде [`int`](https://python-all.ru/3.11/library/functions.html#int).650651Поддерживаются четыре операции, задаваемые следующими комбинациями аргументов:652653- `seek(0, SEEK_SET)`: Перемотка в начало потока.654- `seek(cookie, SEEK_SET)`: Восстановление предыдущей позиции; *cookie* **должен быть** числом, возвращённым [`tell()`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper.tell).655- `seek(0, SEEK_END)`: Перемотка в конец потока.656- `seek(0, SEEK_CUR)`: Оставить текущую позицию потока без изменений.657658Любые другие комбинации аргументов недопустимы и могут вызывать исключения.659660> **См. также**661>662> [`os.SEEK_SET`](https://python-all.ru/3.11/library/os.html#os.SEEK_SET), [`os.SEEK_CUR`](https://python-all.ru/3.11/library/os.html#os.SEEK_CUR) и [`os.SEEK_END`](https://python-all.ru/3.11/library/os.html#os.SEEK_END).663664#### `tell()`665666Возвращает позицию потока в виде непрозрачного числа. Возвращаемое значение `tell()` можно передать в [`seek()`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper.seek), чтобы восстановить предыдущую позицию потока.667668#### `class io.StringIO(initial_value='', newline='\n')`669670Текстовый поток, использующий буфер в памяти. Он наследуется от [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase).671672Текстовый буфер отбрасывается, когда вызывается метод [`close()`](https://python-all.ru/3.11/library/io.html#io.IOBase.close).673674Начальное значение буфера можно задать, указав *initial\_value*. Если включено преобразование newline, символы новой строки будут кодироваться так, как если бы это делал [`write()`](https://python-all.ru/3.11/library/io.html#io.TextIOBase.write). Поток позиционируется на начало буфера, что имитирует открытие существующего файла в режиме `w+`, делая его готовым к немедленной записи с начала или к записи, которая перезапишет начальное значение. Чтобы имитировать открытие файла в режиме `a+` , готовом для добавления, используйте `f.seek(0, io.SEEK_END)` для перемещения потока в конец буфера.675676Аргумент *newline* работает так же, как у [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper), за исключением того, что при записи вывода в поток, если *newline* равен `None`, символы новой строки записываются как `\n` на всех платформах.677678[`StringIO`](https://python-all.ru/3.11/library/io.html#io.StringIO) предоставляет этот метод в дополнение к методам из [`TextIOBase`](https://python-all.ru/3.11/library/io.html#io.TextIOBase) и [`IOBase`](https://python-all.ru/3.11/library/io.html#io.IOBase):679680#### `getvalue()`681682Возвращает [`str`](https://python-all.ru/3.11/library/stdtypes.html#str), содержащий всё содержимое буфера. Символы новой строки декодируются так, как если бы это делал [`read()`](https://python-all.ru/3.11/library/io.html#io.TextIOBase.read), хотя позиция потока не изменяется.683684Пример использования:685686```python687import io688689output = io.StringIO()690output.write('First line.\n')691print('Second line.', file=output)692693# Извлечь содержимое файла – это будет694# 'Первая строка.695Вторая строка.696'697contents = output.getvalue()698699# Закрыть объект и освободить буфер памяти –700# .getvalue() теперь будет вызывать исключение.701output.close()702```703704#### `class io.IncrementalNewlineDecoder`705706Вспомогательный кодек, который декодирует символы новой строки для режима [universal newlines](https://python-all.ru/3.11/glossary.html#term-universal-newlines). Он наследуется от [`codecs.IncrementalDecoder`](https://python-all.ru/3.11/library/codecs.html#codecs.IncrementalDecoder).707708## Производительность709710В этом разделе рассматривается производительность предоставленных конкретных реализаций ввода-вывода.711712### Двоичный ввод-вывод713714Читая и записывая только большие блоки данных, даже когда пользователь запрашивает один байт, буферизованный ввод-вывод скрывает любую неэффективность вызова и выполнения небуферизованных процедур ввода-вывода операционной системы. Выигрыш зависит от ОС и типа выполняемого ввода-вывода. Например, в некоторых современных ОС, таких как Linux, небуферизованный дисковый ввод-вывод может быть таким же быстрым, как буферизованный. Однако суть в том, что буферизованный ввод-вывод обеспечивает предсказуемую производительность независимо от платформы и нижележащего устройства. Поэтому для двоичных данных почти всегда предпочтительнее использовать буферизованный ввод-вывод, а не небуферизованный.715716### Текстовый ввод-вывод717718Текстовый ввод-вывод поверх двоичного хранилища (например, файла) значительно медленнее, чем двоичный ввод-вывод поверх того же хранилища, поскольку требует преобразований между юникодом и двоичными данными с использованием кодека символов. Это может стать заметным при обработке огромных объёмов текстовых данных, таких как большие файлы журналов. Кроме того, [`tell()`](https://python-all.ru/3.11/library/io.html#io.TextIOBase.tell) и [`seek()`](https://python-all.ru/3.11/library/io.html#io.TextIOBase.seek) оба довольно медленны из-за используемого алгоритма реконструкции.719720[`StringIO`](https://python-all.ru/3.11/library/io.html#io.StringIO), однако, является встроенным контейнером юникода в памяти и будет демонстрировать скорость, аналогичную [`BytesIO`](https://python-all.ru/3.11/library/io.html#io.BytesIO).721722### Многопоточность723724Объекты [`FileIO`](https://python-all.ru/3.11/library/io.html#io.FileIO) потокобезопасны настолько, насколько потокобезопасны вызовы операционной системы (такие как *[read(2)](https://python-all.ru/3.11/library/io.html)* в Unix), которые они оборачивают.725726Двоичные буферизованные объекты (экземпляры [`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader), [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter), [`BufferedRandom`](https://python-all.ru/3.11/library/io.html#io.BufferedRandom) и [`BufferedRWPair`](https://python-all.ru/3.11/library/io.html#io.BufferedRWPair)) защищают свои внутренние структуры с помощью блокировки; поэтому их можно безопасно вызывать из нескольких потоков одновременно.727728Объекты [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper) не являются потокобезопасными.729730### Повторный вход731732Двоичные буферизованные объекты (экземпляры [`BufferedReader`](https://python-all.ru/3.11/library/io.html#io.BufferedReader), [`BufferedWriter`](https://python-all.ru/3.11/library/io.html#io.BufferedWriter), [`BufferedRandom`](https://python-all.ru/3.11/library/io.html#io.BufferedRandom) и [`BufferedRWPair`](https://python-all.ru/3.11/library/io.html#io.BufferedRWPair)) не являются реентерабельными. Хотя в нормальных ситуациях повторные вызовы не возникают, они могут появиться при выполнении ввода-вывода в обработчике [`signal`](https://python-all.ru/3.11/library/signal.html#module-signal). Если поток пытается повторно войти в буферизованный объект, к которому он уже обращается, возбуждается [`RuntimeError`](https://python-all.ru/3.11/library/exceptions.html#RuntimeError). Обратите внимание, что это не запрещает другому потоку войти в буферизованный объект.733734Вышесказанное неявно распространяется и на текстовые файлы, поскольку функция [`open()`](https://python-all.ru/3.11/library/functions.html#open) оборачивает буферизованный объект внутрь [`TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper). Это включает стандартные потоки и, следовательно, также влияет на встроенную функцию [`print()`](https://python-all.ru/3.11/library/functions.html#print).735