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
.
Інтерфейс модуля високого рівня¶
-
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 argumentspath
,mode
andflags
. Themode
andflags
arguments may have been modified or inferred from the original call.
-
io.
open_code
(path)¶ Відкриває наданий файл у режимі
'rb
. Цю функцію слід використовувати, коли мається на меті розглядати вміст як виконуваний код.path
should be astr
and an absolute path.The behavior of this function may be overridden by an earlier call to the
PyFile_SetOpenCodeHook()
. However, assuming thatpath
is astr
and an absolute path,open_code(path)
should always behave the same asopen(path, 'rb')
. Overriding the behavior is intended for additional validation or preprocessing of the file.Нове в версії 3.8.
-
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 ofreadinto()
andreadline()
.
На вершині ієрархії введення-виведення знаходиться абстрактний базовий клас 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 readable, writable, 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 |
Успадковує |
Методи заглушки |
Методи та властивості Міксіна |
---|---|---|---|
|
|
||
|
Успадковані методи |
||
|
Успадковані методи |
||
|
Успадковані методи |
Базові класи введення/виведення¶
-
class
io.
IOBase
¶ Абстрактний базовий клас для всіх класів введення-виведення.
Цей клас забезпечує порожні абстрактні реалізації для багатьох методів, які похідні класи можуть вибірково перевизначати; реалізація за замовчуванням представляє файл, який не можна прочитати, записати або шукати.
Even though
IOBase
does not declareread()
orwrite()
because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise aValueError
(orUnsupportedOperation
) 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).
-
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 callingfile.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
or0
– start of the stream (the default); offset should be zero or positiveSEEK_CUR
or1
– current stream position; offset may be negativeSEEK_END
or2
– 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
oros.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. IfFalse
,write()
andtruncate()
will raiseOSError
.
-
writelines
(lines, /)¶ Напишіть список рядків у потік. Роздільники рядків не додаються, тому зазвичай для кожного з наданих рядків є роздільник рядків у кінці.
-
-
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
. Це не є частиною APIBufferedIOBase
і може не існувати в деяких реалізаціях.
-
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()
andwrite()
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 theclose()
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.
-
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 inheritsBufferedIOBase
.Під час зчитування даних із цього об’єкта більший обсяг даних може бути запрошений із базового необробленого потоку та зберігатися у внутрішньому буфері. Потім буферизовані дані можна повернути безпосередньо під час наступних читань.
Конструктор створює
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 inheritsBufferedIOBase
.Під час запису в цей об’єкт дані зазвичай поміщаються у внутрішній буфер. Буфер буде записано в базовий об’єкт
RawIOBase
за різних умов, зокрема:коли буфер стає занадто малим для всіх незавершених даних;
when
flush()
is called;when a
seek()
is requested (forBufferedRandom
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 inheritsBufferedReader
andBufferedWriter
.Конструктор створює читач і записувач для шуканого необробленого потоку, заданого в першому аргументі. Якщо buffer_size опущено, за замовчуванням буде
DEFAULT_BUFFER_SIZE
.BufferedRandom
is capable of anythingBufferedReader
orBufferedWriter
can do. In addition,seek()
andtell()
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 inheritsBufferedIOBase
.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
. Це не є частиною APITextIOBase
і може не існувати в деяких реалізаціях.
-
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
or0
: seek from the start of the stream (the default); offset must either be a number returned byTextIOBase.tell()
, or zero. Any other offset value produces undefined behaviour.SEEK_CUR
or1
: «seek» to the current position; offset must be zero, which is a no-operation (all other values are unsupported).SEEK_END
or2
: 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 inheritsTextIOBase
.encoding gives the name of the encoding that the stream will be decoded or encoded with. It defaults to
locale.getpreferredencoding(False)
.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 towrite()
are guaranteed not to be buffered: any data written on theTextIOWrapper
object is immediately handled to its underlying binary buffer.Змінено в версії 3.3: Додано аргумент write_through.
Змінено в версії 3.3: Типовим кодуванням тепер є
locale.getpreferredencoding(False)
замістьlocale.getpreferredencoding()
. Не змінюйте тимчасово кодування мови за допомогоюlocale.setlocale()
, використовуйте поточне кодування мови замість кодування, яке вибирає користувач.TextIOWrapper
надає ці атрибути даних і методи на додачу до тих, що є вTextIOBase
іIOBase
:-
line_buffering
¶ Чи ввімкнено буферизацію рядків.
-
write_through
¶ Чи передаються записи негайно до базового двійкового буфера.
Нове в версії 3.7.
-
reconfigure
(*[, encoding][, errors][, newline][, line_buffering][, write_through])¶ Переконфігуруйте цей текстовий потік, використовуючи нові налаштування для кодування, помилок, нового рядка, 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 byread()
, 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.