# `io` — Core tools for working with streams

Вихідний код: Lib/io.py

## Огляд

Модуль `io` надає основні можливості Python для роботи з різними типами введення-виведення. Існує три основні типи введення-виведення: текстовий ввід-вивід, бінарний ввід-вивід і необроблений ввід-вивід. Це загальні категорії, і для кожної з них можна використовувати різні резервні сховища. Конкретний об’єкт, що належить до будь-якої з цих категорій, називається file object. Іншими поширеними термінами є потік і файлоподібний об’єкт.

Незалежно від категорії, кожен конкретний об’єкт потоку також матиме різні можливості: він може бути лише для читання, лише для запису або для читання-запису. Він також може дозволити довільний довільний доступ (пошук вперед або назад до будь-якого місця) або лише послідовний доступ (наприклад, у випадку розетки чи труби).

All streams are careful about the type of data you give to them. For example giving a `str` object to the `write()` method of a binary stream will raise a `TypeError`. So will giving a `bytes` object to the `write()` method of a text stream.

Змінено в версії 3.3: Операції, які раніше викликали `IOError`, тепер викликають `OSError`, оскільки `IOError` тепер є псевдонімом `OSError`.

### Текстовий ввід/вивід

Текстовий ввід-вивід очікує та створює об’єкти `str`. Це означає, що щоразу, коли резервне сховище спочатку складається з байтів (наприклад, у випадку файлу), кодування та декодування даних здійснюється прозоро, а також необов’язковий переклад символів нового рядка, характерних для платформи.

The easiest way to create a text stream is with `open()`, optionally specifying an encoding:

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

Текстові потоки в пам’яті також доступні як об’єкти `StringIO`:

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

Примітка

When working with a non-blocking stream, be aware that read operations on text I/O objects might raise a `BlockingIOError` if the stream cannot perform the operation immediately.

API текстового потоку детально описано в документації `TextIOBase`.

### Бінарний ввід-вивід

Двійковий ввід-вивід (також званий буферизований ввід-вивід) очікує байт-подібні об’єкти і створює об’єкти `bytes`. Кодування, декодування чи переклад нового рядка не виконується. Цю категорію потоків можна використовувати для всіх видів нетекстових даних, а також, коли потрібне ручне керування обробкою текстових даних.

The easiest way to create a binary stream is with `open()` with `'b'` in the mode string:

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

Двійкові потоки в пам’яті також доступні як об’єкти `BytesIO`:

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

API бінарного потоку детально описано в документах `BufferedIOBase`.

Інші бібліотечні модулі можуть надавати додаткові способи створення текстових або бінарних потоків. Дивіться, наприклад, `socket.socket.makefile()`.

### Необроблений ввід-вивід

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

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

API необробленого потоку детально описано в документах `RawIOBase`.

## Кодування тексту

Кодування за замовчуванням для `TextIOWrapper` та `open()` залежить від локалі (`locale.getencoding()`).

Однак багато розробників забувають вказати кодування під час відкриття текстових файлів, закодованих у UTF-8 (наприклад, JSON, TOML, Markdown тощо), оскільки більшість платформ Unix за умовчанням використовують локаль UTF-8. Це спричиняє помилки, оскільки кодування мови не є UTF-8 для більшості користувачів Windows. Наприклад:

    # May not work on Windows when non-ASCII characters in the file.
    with open("README.md") as f:
        long_description = f.read()

Accordingly, it is highly recommended that you specify the encoding explicitly when opening text files. If you want to use UTF-8, pass `encoding="utf-8"`. To use the current locale encoding, `encoding="locale"` is supported since Python 3.10.

Дивись також

Режим Python UTF-8

  Python UTF-8 Mode can be used to change the default encoding to UTF-8 from locale-specific encoding.

PEP 686

  Python 3.15 will make Режим Python UTF-8 default.

### Увімкніть EncodingWarning

Added in version 3.10: Дивіться PEP 597 для більш детальної інформації.

To find where the default locale encoding is used, you can enable the `-X warn_default_encoding` command line option or set the `PYTHONWARNDEFAULTENCODING` environment variable, which will emit an `EncodingWarning` when the default encoding is used.

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

## Інтерфейс модуля високого рівня

io.DEFAULT_BUFFER_SIZE

  Int, що містить стандартний розмір буфера, який використовується буферизованими класами вводу-виводу модуля. `open()` використовує blksize файлу (отриманий `os.stat()`), якщо це можливо.

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

  Це псевдонім вбудованої функції `open()`.

  This function raises an auditing event `open` with arguments path, mode and flags. The mode and flags arguments may have been modified or inferred from the original call.

io.open_code(path)

  Відкриває наданий файл у режимі `'rb`. Цю функцію слід використовувати, коли мається на меті розглядати вміст як виконуваний код.

  path should be a `str` and an absolute path.

  The behavior of this function may be overridden by an earlier call to the `PyFile_SetOpenCodeHook()`. However, assuming that path is a `str` and an absolute path, `open_code(path)` should always behave the same as `open(path, 'rb')`. Overriding the behavior is intended for additional validation or preprocessing of the file.

  Added in version 3.8.

io.text_encoding(encoding, stacklevel=2, /)

  Це допоміжна функція для викликів, які використовують `open()` або `TextIOWrapper` і мають параметр `encoding=None`.

  This function returns encoding if it is not `None`. Otherwise, it returns `"locale"` or `"utf-8"` depending on UTF-8 Mode.

  This function emits an `EncodingWarning` if `sys.flags.warn_default_encoding` is true and encoding is `None`. stacklevel specifies where the warning is emitted. For example:

      def read_text(path, encoding=None):
          encoding = io.text_encoding(encoding)  # stacklevel=2
          with open(path, encoding) as f:
              return f.read()

  У цьому прикладі `EncodingWarning` видається для викликаючого `read_text()`.

  Перегляньте Кодування тексту для отримання додаткової інформації.

  Added in version 3.10.

  Змінено в версії 3.11: `text_encoding()` returns «utf-8» when UTF-8 mode is enabled and encoding is `None`.

exception io.BlockingIOError

  Це псевдонім сумісності для вбудованого винятку `BlockingIOError`.

exception io.UnsupportedOperation

  Виняток, що успадковує `OSError` і `ValueError`, який виникає, коли в потоці викликається непідтримувана операція.

Дивись також

`sys`

  містить стандартні потоки вводу-виводу: `sys.stdin`, `sys.stdout` і `sys.stderr`.

## Ієрархія класів

Реалізація потоків введення-виведення організована як ієрархія класів. Спочатку абстрактні базові класи (ABC), які використовуються для визначення різних категорій потоків, потім конкретні класи, що забезпечують реалізацію стандартних потоків.

Примітка

The abstract base classes also provide default implementations of some methods in order to help implementation of concrete stream classes. For example, `BufferedIOBase` provides unoptimized implementations of `readinto()` and `readline()`.

На вершині ієрархії введення-виведення знаходиться абстрактний базовий клас `IOBase`. Він визначає базовий інтерфейс для потоку. Зауважте, однак, що немає розділення між читанням і записом у потоки; реалізаціям дозволено викликати `UnsupportedOperation`, якщо вони не підтримують дану операцію.

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

The `BufferedIOBase` ABC extends `IOBase`. It deals with buffering on a raw binary stream (`RawIOBase`). Its subclasses, `BufferedWriter`, `BufferedReader`, and `BufferedRWPair` buffer raw binary streams that are writable, readable, and both readable and writable, respectively. `BufferedRandom` provides a buffered interface to seekable streams. Another `BufferedIOBase` subclass, `BytesIO`, is a stream of in-memory bytes.

`TextIOBase` ABC розширює `IOBase`. Він має справу з потоками, байти яких представляють текст, і обробляє кодування та декодування до та з рядків. `TextIOWrapper`, який розширює `TextIOBase`, є буферизованим текстовим інтерфейсом для буферизованого необробленого потоку (`BufferedIOBase`). Нарешті, `StringIO` — це потік тексту в пам’яті.

Назви аргументів не є частиною специфікації, і лише аргументи `open()` призначені для використання як аргументи ключових слів.

У наведеній нижче таблиці підсумовуються азбуки, надані модулем `io`:

ABC | Успадковує | Методи заглушки | Методи та властивості Міксіна
--- | --- | --- | ---
`IOBase` |  | `fileno`, `seek` і `truncate` | `close`, `closed`, `__enter__`, `__exit__`, `flush`, `isatty`, `__iter__`, `__next__`, `readable`, `readline`, `readlines`, `seekable`, `tell`, `writable` і `writelines`
`RawIOBase` | `IOBase` | `readinto` і `write` | Успадковані методи `IOBase`, `read` і `readall`
`BufferedIOBase` | `IOBase` | `detach`, `read`, `read1` і `write` | Успадковані методи `IOBase`, `readinto` і `readinto1`
`TextIOBase` | `IOBase` | `detach`, `read`, `readline` і `write` | Успадковані методи `IOBase`, `encoding`, `errors` та `newlines`

### Базові класи введення/виведення

class io.IOBase

  Абстрактний базовий клас для всіх класів введення-виведення.

  Цей клас забезпечує порожні абстрактні реалізації для багатьох методів, які похідні класи можуть вибірково перевизначати; реалізація за замовчуванням представляє файл, який не можна прочитати, записати або шукати.

  Even though `IOBase` does not declare `read()` or `write()` because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise a `ValueError` (or `UnsupportedOperation`) when operations they do not support are called.

  Основний тип, який використовується для зчитування чи запису у файл двійкових даних, це `bytes`. Інші байтоподібні об’єкти також приймаються як аргументи методу. Текстові класи введення/виведення працюють з даними `str`.

  Зверніть увагу, що виклик будь-якого методу (навіть запитів) у закритому потоці не визначений. У цьому випадку реалізації можуть викликати `ValueError`.

  `IOBase` (та його підкласи) підтримує протокол ітератора, що означає, що об’єкт `IOBase` може повторюватися, повертаючи рядки в потік. Рядки визначаються дещо по-різному залежно від того, чи є потік двійковим потоком (передає байти) чи текстовим потоком (передає рядки символів). Див. `readline()` нижче.

  `IOBase` також є контекстним менеджером і тому підтримує оператор `with`. У цьому прикладі файл закривається після завершення набору інструкцій `with` — навіть якщо виникає виняток:

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

  `IOBase` надає такі атрибути даних і методи:

  close()

    Промийте та закрийте цей потік. Цей метод не діє, якщо файл уже закрито. Після закриття файлу будь-яка операція з файлом (наприклад, читання або запис) викличе `ValueError`.

    Для зручності цей метод можна викликати кілька разів; але лише перший дзвінок матиме ефект.

  closed

    `True`, якщо потік закрито.

  fileno()

    Повертає базовий дескриптор файлу (ціле число) потоку, якщо він існує. `OSError` виникає, якщо об’єкт IO не використовує дескриптор файлу.

  flush()

    Очистіть буфери запису потоку, якщо це можливо. Це нічого не робить для потоків лише для читання та неблокуючих потоків.

  isatty()

    Повертає `True`, якщо потік інтерактивний (тобто підключений до терміналу/пристрою tty).

  readable()

    Return `True` if the stream can be read from. If `False`, `read()` will raise `OSError`.

  readline(size=-1, /)

    Прочитайте та поверніть один рядок із потоку. Якщо вказано size, буде прочитано не більше size байтів.

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

  readlines(hint=-1, /)

    Читання та повернення списку рядків із потоку. Можна вказати hint, щоб контролювати кількість прочитаних рядків: рядки більше не читатимуться, якщо загальний розмір (у байтах/символах) усіх рядків на даний момент перевищує hint.

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

    Note that it’s already possible to iterate on file objects using `for line in file: ...` without calling `file.readlines()`.

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

    Change the stream position to the given byte offset, interpreted relative to the position indicated by whence, and return the new absolute position. Values for whence are:

    - `os.SEEK_SET` or `0` – start of the stream (the default); offset should be zero or positive

    - `os.SEEK_CUR` or `1` – current stream position; offset may be negative

    - `os.SEEK_END` or `2` – end of the stream; offset is usually negative

    Added in version 3.1: The `SEEK_*` constants.

    Added in version 3.3: Some operating systems could support additional values, like `os.SEEK_HOLE` or `os.SEEK_DATA`. The valid values for a file could depend on it being open in text or binary mode.

  seekable()

    Повертає `True`, якщо потік підтримує довільний доступ. Якщо `False`, `seek()`, `tell()` і `truncate()` викличуть `OSError`.

  tell()

    Повернути поточну позицію потоку.

  truncate(size=None, /)

    Змініть розмір потоку до вказаного size у байтах (або поточної позиції, якщо size не вказано). Поточна позиція потоку не змінена. Ця зміна розміру може збільшити або зменшити поточний розмір файлу. У разі розширення вміст нової файлової області залежить від платформи (у більшості систем додаткові байти заповнюються нулями). Повернеться новий розмір файлу.

    Змінено в версії 3.5: Windows тепер заповнюватиме файли нулем під час розширення.

  writable()

    Return `True` if the stream supports writing. If `False`, `write()` and `truncate()` will raise `OSError`.

  writelines(lines, /)

    Напишіть список рядків у потік. Роздільники рядків не додаються, тому зазвичай для кожного з наданих рядків є роздільник рядків у кінці.

  __del__()

    Підготуйтеся до руйнування об’єкта. `IOBase` забезпечує реалізацію цього методу за замовчуванням, яка викликає метод екземпляра `close()`.

class io.RawIOBase

  Base class for raw binary streams. It inherits from `IOBase`.

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

  `RawIOBase` надає ці методи на додаток до методів з `IOBase`:

  read(size=-1, /)

    Прочитати до size байтів з об’єкта та повернути їх. Для зручності, якщо size не вказано або -1, повертаються всі байти до EOF. В іншому випадку буде зроблено лише один системний виклик. Якщо виклик операційної системи повертає менше size байтів, може бути повернуто менше ніж size байт.

    Якщо повертається 0 байтів, а size не дорівнює 0, це вказує на кінець файлу. Якщо об’єкт перебуває в неблокуючому режимі і немає доступних байтів, повертається «Немає».

    Реалізація за замовчуванням відноситься до `readall()` і `readinto()`.

  readall()

    Прочитати та повернути всі байти з потоку до EOF, використовуючи кілька викликів потоку, якщо необхідно.

  readinto(b, /)

    Читання байтів у попередньо виділений записуваний bytes-like object b і повернення кількості прочитаних байтів. Наприклад, b може бути `bytearray`. Якщо об’єкт перебуває в неблокуючому режимі і немає доступних байтів, повертається «Немає».

  write(b, /)

    Запишіть заданий bytes-like object, b, до базового необробленого потоку та поверніть кількість записаних байтів. Це може бути менше, ніж довжина b в байтах, залежно від специфіки базового необробленого потоку, особливо якщо він знаходиться в неблокуючому режимі. `None` повертається, якщо необроблений потік налаштовано на неблокування і жоден байт не може бути легко записаний до нього. Виклик може звільнити або змінити b після повернення цього методу, тому реалізація має звертатися до b лише під час виклику методу.

class io.BufferedIOBase

  Base class for binary streams that support some kind of buffering. It inherits from `IOBase`.

  The main difference with `RawIOBase` is that methods `read()`, `readinto()` and `write()` will try (respectively) to read as much input as requested or to emit all provided data.

  In addition, if the underlying raw stream is in non-blocking mode, when the system returns would block `write()` will raise `BlockingIOError` with `BlockingIOError.characters_written` and `read()` will return data read so far or `None` if no data is available.

  Крім того, метод `read()` не має реалізації за замовчуванням, яка відповідає `readinto()`.

  Типова реалізація `BufferedIOBase` не повинна успадковувати реалізацію `RawIOBase`, а повинна обгортати її, як це роблять `BufferedWriter` і `BufferedReader`.

  `BufferedIOBase` надає або замінює ці атрибути та методи даних на додачу до тих, що є в `IOBase`:

  raw

    Основний необроблений потік (екземпляр `RawIOBase`), з яким працює `BufferedIOBase`. Це не є частиною API `BufferedIOBase` і може не існувати в деяких реалізаціях.

  detach()

    Відокремте базовий необроблений потік від буфера та поверніть його.

    Після від’єднання необробленого потоку буфер перебуває в непридатному для використання стані.

    Деякі буфери, наприклад `BytesIO`, не мають концепції єдиного необробленого потоку, який повертається з цього методу. Вони викликають `UnsupportedOperation`.

    Added in version 3.1.

  read(size=-1, /)

    Read and return up to size bytes. If the argument is omitted, `None`, or negative read as much as possible.

    Fewer bytes may be returned than requested. An empty `bytes` object is returned if the stream is already at EOF. More than one read may be made and calls may be retried if specific errors are encountered, see `os.read()` and PEP 475 for more details. Less than size bytes being returned does not imply that EOF is imminent.

    When reading as much as possible the default implementation will use `raw.readall` if available (which should implement `RawIOBase.readall()`), otherwise will read in a loop until read returns `None`, an empty `bytes`, or a non-retryable error. For most streams this is to EOF, but for non-blocking streams more data may become available.

    Примітка

    When the underlying raw stream is non-blocking, implementations may either raise `BlockingIOError` or return `None` if no data is available. `io` implementations return `None`.

  read1(size=-1, /)

    Read and return up to size bytes, calling `readinto()` which may retry if `EINTR` is encountered per PEP 475. If size is `-1` or not provided, the implementation will choose an arbitrary value for size.

    Примітка

    When the underlying raw stream is non-blocking, implementations may either raise `BlockingIOError` or return `None` if no data is available. `io` implementations return `None`.

  readinto(b, /)

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

    Подібно до `read()`, кілька читань можуть бути видані базовому необробленому потоку, якщо останній не є інтерактивним.

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

  readinto1(b, /)

    Зчитування байтів у попередньо виділений записуваний bytes-like object b, використовуючи щонайбільше один виклик базового необробленого потоку `read()` (або `метод readinto()`). Повертає кількість прочитаних байтів.

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

    Added in version 3.5.

  write(b, /)

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

    У неблокуючому режимі виникає `BlockingIOError`, якщо дані потрібно було записати в необроблений потік, але він не міг прийняти всі дані без блокування.

    Виклик може звільнити або змінити b після повернення цього методу, тому реалізація має звертатися до b лише під час виклику методу.

### Необроблений файл введення-виведення

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

  A raw binary stream representing an OS-level file containing bytes data. It inherits from `RawIOBase`.

  Ім’я може бути одним із двох:

  - рядок символів або об’єкт `bytes`, що представляє шлях до файлу, який буде відкрито. У цьому випадку closefd має бути `True` (за замовчуванням), інакше виникне помилка.

  - ціле число, що представляє номер існуючого файлового дескриптора рівня ОС, до якого отриманий об’єкт `FileIO` надасть доступ. Коли об’єкт FileIO закрито, цей fd також буде закрито, якщо для closefd не встановлено значення `False`.

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

  The `read()` (when called with a positive argument), `readinto()` and `write()` methods on this class will only make one system call.

  Спеціальний відкривач можна використовувати, передавши виклик як opener. Базовий дескриптор файлу для об’єкта файлу потім отримується шляхом виклику opener з (name, flags). opener має повертати дескриптор відкритого файлу (передача `os.open` як opener призводить до функціональності, подібної до передачі `None`).

  Щойно створений файл не успадковується.

  Перегляньте вбудовану функцію `open()` для прикладів використання параметра opener.

  Змінено в версії 3.3: Додано параметр opener. Додано режим `'x`.

  Змінено в версії 3.4: Тепер файл не успадковується.

  `FileIO` надає ці атрибути даних на додаток до атрибутів з `RawIOBase` і `IOBase`:

  mode

    Режим, заданий у конструкторі.

  name

    Ім’я файлу. Це дескриптор файлу, якщо в конструкторі не вказано ім’я.

### Буферизовані потоки

Буферизовані потоки вводу-виводу забезпечують інтерфейс вищого рівня для пристрою вводу-виводу, ніж необроблений ввід-вивод.

class io.BytesIO(initial_bytes=b'')

  A binary stream using an in-memory bytes buffer. It inherits from `BufferedIOBase`. The buffer is discarded when the `close()` method is called.

  Необов’язковий аргумент initial_bytes — це bytes-like object, який містить початкові дані.

  `BytesIO` надає або замінює ці методи на додаток до методів з `BufferedIOBase` і `IOBase`:

  getbuffer()

    Повернути доступний для читання та запису перегляд вмісту буфера без його копіювання. Крім того, зміна перегляду прозоро оновить вміст буфера:

        >>> b = io.BytesIO(b"abcdef")
        >>> view = b.getbuffer()
        >>> view[2:4] = b"56"
        >>> b.getvalue()
        b'ab56ef'

    Примітка

    Поки представлення існує, об’єкт `BytesIO` не можна змінити розмір або закрити.

    Added in version 3.2.

  getvalue()

    Повертає `bytes`, що містить увесь вміст буфера.

  read1(size=-1, /)

    У `BytesIO` це те саме, що `read()`.

    Змінено в версії 3.7: Аргумент size тепер необов’язковий.

  readinto1(b, /)

    У `BytesIO` це те саме, що `readinto()`.

    Added in version 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a readable, non seekable `RawIOBase` raw binary stream. It inherits from `BufferedIOBase`.

  Під час зчитування даних із цього об’єкта більший обсяг даних може бути запрошений із базового необробленого потоку та зберігатися у внутрішньому буфері. Потім буферизовані дані можна повернути безпосередньо під час наступних читань.

  Конструктор створює `BufferedReader` для даного доступного для читання потоку raw і buffer_size. Якщо buffer_size опущено, `DEFAULT_BUFFER_SIZE` використовується.

  `BufferedReader` надає або замінює ці методи на додаток до методів з `BufferedIOBase` і `IOBase`:

  peek(size=0, /)

    Return bytes from the stream without advancing the position. The number of bytes returned may be less or more than requested. If the underlying raw stream is non-blocking and the operation would block, returns empty bytes.

  read(size=-1, /)

    In `BufferedReader` this is the same as `io.BufferedIOBase.read()`

  read1(size=-1, /)

    In `BufferedReader` this is the same as `io.BufferedIOBase.read1()`

    Змінено в версії 3.7: Аргумент size тепер необов’язковий.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a writeable, non seekable `RawIOBase` raw binary stream. It inherits from `BufferedIOBase`.

  Під час запису в цей об’єкт дані зазвичай поміщаються у внутрішній буфер. Буфер буде записано в базовий об’єкт `RawIOBase` за різних умов, зокрема:

  - коли буфер стає занадто малим для всіх незавершених даних;

  - when `flush()` is called;

  - when a `seek()` is requested (for `BufferedRandom` objects);

  - коли об’єкт `BufferedWriter` закрито або знищено.

  Конструктор створює `BufferedWriter` для заданого записуваного необробленого потоку. Якщо buffer_size не вказано, за умовчанням він `DEFAULT_BUFFER_SIZE`.

  `BufferedWriter` надає або замінює ці методи на додаток до методів з `BufferedIOBase` і `IOBase`:

  flush()

    Примусове переміщення байтів, що зберігаються в буфері, у необроблений потік. `BlockingIOError` має бути викликано, якщо необроблений потік блокується.

  write(b, /)

    Write the bytes-like object, b, and return the number of bytes written. When in non-blocking mode, a `BlockingIOError` with `BlockingIOError.characters_written` set is raised if the buffer needs to be written out but the raw stream blocks.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a seekable `RawIOBase` raw binary stream. It inherits from `BufferedReader` and `BufferedWriter`.

  Конструктор створює читач і записувач для шуканого необробленого потоку, заданого в першому аргументі. Якщо buffer_size опущено, за замовчуванням буде `DEFAULT_BUFFER_SIZE`.

  `BufferedRandom` is capable of anything `BufferedReader` or `BufferedWriter` can do. In addition, `seek()` and `tell()` are guaranteed to be implemented.

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

  A buffered binary stream providing higher-level access to two non seekable `RawIOBase` raw binary streams—one readable, the other writeable. It inherits from `BufferedIOBase`.

  reader і writer є об’єктами `RawIOBase`, які доступні для читання та запису відповідно. Якщо buffer_size опущено, за замовчуванням буде `DEFAULT_BUFFER_SIZE`.

  `BufferedRWPair` реалізує всі методи `BufferedIOBase`за винятком `detach()`, який викликає `UnsupportedOperation`.

  Попередження

  `BufferedRWPair` не намагається синхронізувати доступ до базових необроблених потоків. Ви не повинні передавати йому той самий об’єкт, що й читач і запис; замість цього використовуйте `BufferedRandom`.

### Текстовий ввід/вивід

class io.TextIOBase

  Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits from `IOBase`.

  `TextIOBase` надає або замінює ці атрибути та методи даних на додачу до тих, що є в `IOBase`:

  encoding

    Назва кодування, яке використовується для декодування байтів потоку в рядки та для кодування рядків у байти.

  errors

    Налаштування помилки декодера або кодера.

  newlines

    Рядок, кортеж рядків або `None`, що вказує перекладені на даний момент нові рядки. Залежно від реалізації та початкових прапорів конструктора, це може бути недоступним.

  buffer

    The underlying binary buffer (a `BufferedIOBase` or `RawIOBase` instance) that `TextIOBase` deals with. This is not part of the `TextIOBase` API and may not exist in some implementations.

  detach()

    Відокремте базовий бінарний буфер від `TextIOBase` і поверніть його.

    Після того, як основний буфер було від’єднано, `TextIOBase` перебуває в непридатному для використання стані.

    Деякі реалізації `TextIOBase`, наприклад `StringIO`, можуть не мати концепції основного буфера, і виклик цього методу призведе до `UnsupportedOperation`.

    Added in version 3.1.

  read(size=-1, /)

    Читати та повертати не більше символів size із потоку як один `str`. Якщо size є від’ємним або `None`, читається до EOF.

  readline(size=-1, /)

    Read until newline or EOF and return a single `str`. If the stream is already at EOF, an empty string is returned.

    Якщо вказано size, буде прочитано не більше символів size.

  seek(offset, whence=SEEK_SET, /)

    Change the stream position to the given offset. Behaviour depends on the whence parameter. The default value for whence is `SEEK_SET`.

    - `SEEK_SET` or `0`: seek from the start of the stream (the default); offset must either be a number returned by `TextIOBase.tell()`, or zero. Any other offset value produces undefined behaviour.

    - `SEEK_CUR` or `1`: «seek» to the current position; offset must be zero, which is a no-operation (all other values are unsupported).

    - `SEEK_END` or `2`: seek to the end of the stream; offset must be zero (all other values are unsupported).

    Повертає нову абсолютну позицію як непрозоре число.

    Added in version 3.1: The `SEEK_*` constants.

  tell()

    Повертає поточну позицію потоку як непрозоре число. Число зазвичай не означає кількість байтів у базовому двійковому сховищі.

  write(s, /)

    Запишіть рядок s у потік і поверніть кількість записаних символів.

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

  A buffered text stream providing higher-level access to a `BufferedIOBase` buffered binary stream. It inherits from `TextIOBase`.

  encoding gives the name of the encoding that the stream will be decoded or encoded with. In UTF-8 Mode, this defaults to UTF-8. Otherwise, it defaults to `locale.getencoding()`. `encoding="locale"` can be used to specify the current locale’s encoding explicitly. See Кодування тексту for more information.

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

  новий рядок контролює, як обробляються закінчення рядків. Це може бути `None`, `''`, `'\n'`, `'\r'` і `'\r\n'`. Він працює наступним чином:

  - Під час читання вхідних даних із потоку, якщо новий рядок має значення `None`, увімкнено режим universal newlines. Рядки у вхідних даних можуть закінчуватися на `'\n'`, `'\r'` або `'\r\n'`, і вони перекладаються на `'\n'` перед поверненням до абонента. Якщо новий рядок дорівнює `''`, універсальний режим нових рядків увімкнено, але закінчення рядків повертаються абоненту без перекладу. Якщо новий рядок має будь-яке з інших дозволених значень, рядки вводу завершуються лише заданим рядком, а закінчення рядка повертається абоненту без перекладу.

  - Під час запису вихідних даних у потік, якщо новий рядок має значення `None`, будь-які записані символи `'\n'` переводяться в системний роздільник рядків за умовчанням, `os.linesep`. Якщо новий рядок є `''` або `'\n'`, переклад не відбувається. Якщо новий рядок є будь-яким іншим дозволеним значенням, будь-які написані символи `'\n'` переводяться в заданий рядок.

  If line_buffering is `True`, `flush()` is implied when a call to write contains a newline character or a carriage return.

  If write_through is `True`, calls to `write()` are guaranteed not to be buffered: any data written on the `TextIOWrapper` object is immediately handled to its underlying binary buffer.

  Змінено в версії 3.3: Додано аргумент write_through.

  Змінено в версії 3.3: Типовим кодуванням тепер є `locale.getpreferredencoding(False)` замість `locale.getpreferredencoding()`. Не змінюйте тимчасово кодування мови за допомогою `locale.setlocale()`, використовуйте поточне кодування мови замість кодування, яке вибирає користувач.

  Змінено в версії 3.10: Аргумент encoding тепер підтримує фіктивну назву кодування `"locale"`.

  Примітка

  When the underlying raw stream is non-blocking, a `BlockingIOError` may be raised if a read operation cannot be completed immediately.

  `TextIOWrapper` надає ці атрибути даних і методи на додачу до тих, що є в `TextIOBase` і `IOBase`:

  line_buffering

    Чи ввімкнено буферизацію рядків.

  write_through

    Чи передаються записи негайно до базового двійкового буфера.

    Added in version 3.7.

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

    Переконфігуруйте цей текстовий потік, використовуючи нові налаштування для кодування, помилок, нового рядка, line_buffering і write_through.

    Параметри, які не вказано, зберігають поточні налаштування, за винятком того, що `errors='strict'` використовується, коли вказано кодування, але не вказано errors.

    Неможливо змінити кодування або новий рядок, якщо деякі дані вже прочитано з потоку. З іншого боку, зміна кодування після запису можлива.

    Цей метод виконує неявне очищення потоку перед встановленням нових параметрів.

    Added in version 3.7.

    Змінено в версії 3.11: The method supports `encoding="locale"` option.

  seek(cookie, whence=os.SEEK_SET, /)

    Set the stream position. Return the new stream position as an `int`.

    Four operations are supported, given by the following argument combinations:

    - `seek(0, SEEK_SET)`: Rewind to the start of the stream.

    - `seek(cookie, SEEK_SET)`: Restore a previous position; cookie must be a number returned by `tell()`.

    - `seek(0, SEEK_END)`: Fast-forward to the end of the stream.

    - `seek(0, SEEK_CUR)`: Leave the current stream position unchanged.

    Any other argument combinations are invalid, and may raise exceptions.

    Дивись також

    `os.SEEK_SET`, `os.SEEK_CUR`, and `os.SEEK_END`.

  tell()

    Return the stream position as an opaque number. The return value of `tell()` can be given as input to `seek()`, to restore a previous stream position.

class io.StringIO(initial_value='', newline='\n')

  A text stream using an in-memory text buffer. It inherits from `TextIOBase`.

  Текстовий буфер відкидається під час виклику методу `close()`.

  The initial value of the buffer can be set by providing initial_value. If newline translation is enabled, newlines will be encoded as if by `write()`. The stream is positioned at the start of the buffer which emulates opening an existing file in a `w+` mode, making it ready for an immediate write from the beginning or for a write that would overwrite the initial value. To emulate opening a file in an `a+` mode ready for appending, use `f.seek(0, io.SEEK_END)` to reposition the stream at the end of the buffer.

  Аргумент новий рядок працює як аргумент `TextIOWrapper`, за винятком того, що під час запису виводу в потік, якщо новий рядок має значення `None`, нові рядки записуються як `\n` на всіх платформах.

  `StringIO` надає цей метод на додаток до методів з `TextIOBase` і `IOBase`:

  getvalue()

    Return a `str` containing the entire contents of the buffer. Newlines are decoded as if by `read()`, although the stream position is not changed.

  Приклад використання:

      import io

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

      # Retrieve file contents -- this will be
      # 'First line.\nSecond line.\n'
      contents = output.getvalue()

      # Close object and discard memory buffer --
      # .getvalue() will now raise an exception.
      output.close()

class io.IncrementalNewlineDecoder

  A helper codec that decodes newlines for universal newlines mode. It inherits from `codecs.IncrementalDecoder`.

## Static Typing

The following protocols can be used for annotating function and method arguments for simple stream reading or writing operations. They are decorated with `@typing.runtime_checkable`.

class io.Reader[T]

  Generic protocol for reading from a file or other input stream. `T` will usually be `str` or `bytes`, but can be any type that is read from the stream.

  Added in version 3.14.

  read()
  read(size, /)

    Read data from the input stream and return it. If size is specified, it should be an integer, and at most size items (bytes/characters) will be read.

  For example:

      def read_it(reader: Reader[str]):
          data = reader.read(11)
          assert isinstance(data, str)

class io.Writer[T]

  Generic protocol for writing to a file or other output stream. `T` will usually be `str` or `bytes`, but can be any type that can be written to the stream.

  Added in version 3.14.

  write(data, /)

    Write data to the output stream and return the number of items (bytes/characters) written.

  For example:

      def write_binary(writer: Writer[bytes]):
          writer.write(b"Hello world!\n")

See ABCs and Protocols for working with I/O for other I/O related protocols and classes that can be used for static type checking.

## Продуктивність

У цьому розділі обговорюється продуктивність наданих конкретних реалізацій введення-виведення.

### Бінарний ввід-вивід

Завдяки читанню та запису лише великих фрагментів даних, навіть якщо користувач запитує один байт, буферизований ввід-вивід приховує будь-яку неефективність виклику та виконання небуферизованих процедур вводу-виводу операційної системи. Коефіцієнт посилення залежить від ОС і типу вводу-виводу, який виконується. Наприклад, у деяких сучасних ОС, таких як Linux, небуферизований дисковий ввід-вивід може бути таким же швидким, як буферизований ввід-вивід. Суть полягає в тому, що буферизований ввід-вивід забезпечує передбачувану продуктивність незалежно від платформи та резервного пристрою. Тому для двійкових даних майже завжди краще використовувати буферизований ввід-вивід, а не небуферизований ввід-вивід.

### Текстовий ввід/вивід

Text I/O over a binary storage (such as a file) is significantly slower than binary I/O over the same storage, because it requires conversions between unicode and binary data using a character codec. This can become noticeable handling huge amounts of text data like large log files. Also, `tell()` and `seek()` are both quite slow due to the reconstruction algorithm used.

`StringIO`, однак, є власним контейнером Юнікоду в пам’яті та демонструватиме таку ж швидкість, як `BytesIO`.

### Багатопотоковість

`FileIO` objects are thread-safe to the extent that the operating system calls (such as read(2) under Unix) they wrap are thread-safe too.

Бінарні буферизовані об’єкти (екземпляри `BufferedReader`, `BufferedWriter`, `BufferedRandom` і `BufferedRWPair`) захищають свої внутрішні структури за допомогою блокування; тому безпечно викликати їх із кількох потоків одночасно.

Об’єкти `TextIOWrapper` не є потокобезпечними.

### Повторна вхідність

Двійкові буферизовані об’єкти (екземпляри `BufferedReader`, `BufferedWriter`, `BufferedRandom` і `BufferedRWPair`) не є реентерабельними. Хоча реентерабельні виклики не відбуваються у звичайних ситуаціях, вони можуть виникнути внаслідок виконання введення/виведення в обробнику `signal`. Якщо потік намагається повторно ввести буферизований об’єкт, до якого він уже має доступ, виникає `RuntimeError`. Зауважте, що це не забороняє іншому потоку входити в буферизований об’єкт.

The above implicitly extends to text files, since the `open()` function will wrap a buffered object inside a `TextIOWrapper`. This includes standard streams and therefore affects the built-in `print()` function as well.