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.