# `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")

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`.

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

The default encoding of `TextIOWrapper` and `open()` is locale-specific (`locale.getpreferredencoding(False)`).

Однак багато розробників забувають вказати кодування під час відкриття текстових файлів, закодованих у 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()

Additionally, while there is no concrete plan as of yet, Python may change the default text file encoding to UTF-8 in the future.

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 in Python 3.10.

When you need to run existing code on Windows that attempts to open UTF-8 files using the default locale encoding, you can enable the UTF-8 mode. See UTF-8 mode on Windows.

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

Нове в версії 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.

  Нове в версії 3.8.

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

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

  This function returns encoding if it is not `None` and `"locale"` if encoding is `None`.

  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()`.

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

  Нове в версії 3.10.

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=SEEK_SET, /)

    Change the stream position to the given byte offset. offset is interpreted relative to the position indicated by whence. The default value for whence is `SEEK_SET`. Values for whence are:

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

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

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

    Return the new absolute position.

    Нове в версії 3.1: The `SEEK_*` constants.

    Нове в версії 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 `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 `IOBase`.

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

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

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

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

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

  `raw`

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

  `detach`()

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

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

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

    Нове в версії 3.1.

  `read`(size=- 1, /)

    Читати та повертати до size байтів. Якщо аргумент пропущений, `None` або негативний, дані зчитуються та повертаються, доки не буде досягнуто EOF. Якщо потік уже знаходиться в EOF, повертається порожній об’єкт `bytes`.

    Якщо аргумент є позитивним, а основний необроблений потік не є інтерактивним, кілька необроблених зчитувань можуть бути видані, щоб задовольнити кількість байтів (якщо спочатку не досягнуто EOF). Але для інтерактивних необроблених потоків буде видано щонайбільше одне необроблене читання, і короткий результат не означає, що EOF неминуча.

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

  `read1`(size=- 1, /)

    Читати та повертати до size байтів, щонайбільше з одним викликом базового необробленого потоку методу `read()` (або `readinto()`). Це може бути корисним, якщо ви реалізуєте власну буферизацію поверх об’єкта `BufferedIOBase`.

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

  `readinto`(b, /)

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

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

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

  `readinto1`(b, /)

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

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

    Нове в версії 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 `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 `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` не можна змінити розмір або закрити.

    Нове в версії 3.2.

  `getvalue`()

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

  `read1`(size=- 1, /)

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

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

  `readinto1`(b, /)

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

    Нове в версії 3.5.

class `io.``BufferedReader`(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

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

  `peek`(size=0, /)

    Повернути байти з потоку без просування позиції. Щоб задовольнити виклик, виконується щонайбільше одне читання необробленого потоку. Кількість повернених байтів може бути меншою або більшою за запитувану.

  `read`(size=- 1, /)

    Читання та повернення байтів size або, якщо size не задано або має від’ємне значення, до EOF або якщо виклик read заблокує в неблокуючому режимі.

  `read1`(size=- 1, /)

    Читайте та повертайте до size байтів лише одним викликом необробленого потоку. Якщо принаймні один байт буферизується, повертаються лише буферизовані байти. В іншому випадку виконується один виклик читання необробленого потоку.

    Змінено в версії 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 `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, /)

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

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 `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 `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 `IOBase`.

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

  `encoding`

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

  `errors`

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

  `newlines`

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

  `buffer`

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

  `detach`()

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

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

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

    Нове в версії 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).

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

    Нове в версії 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 `TextIOBase`.

  encoding gives the name of the encoding that the stream will be decoded or encoded with. It defaults to `locale.getpreferredencoding(False)`. `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"`.

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

  `line_buffering`

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

  `write_through`

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

    Нове в версії 3.7.

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

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

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

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

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

    Нове в версії 3.7.

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

  A text stream using an in-memory text buffer. It inherits `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.

  Аргумент новий рядок працює як аргумент `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 `codecs.IncrementalDecoder`.

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

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

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

Завдяки читанню та запису лише великих фрагментів даних, навіть якщо користувач запитує один байт, буферизований ввід-вивід приховує будь-яку неефективність виклику та виконання небуферизованих процедур вводу-виводу операційної системи. Коефіцієнт посилення залежить від ОС і типу вводу-виводу, який виконується. Наприклад, у деяких сучасних ОС, таких як 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, `TextIOWrapper.tell()` and `TextIOWrapper.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.