io — Основные инструменты для работы с потоками

Исходный код: Lib/io.py

Обзор

Модуль io предоставляет главные средства Python для контакта с различными типами I/O. Существует три основных типа I/O: текстовый I/O, бинарный I/O и сырой I/O. Это универсальные категории, и для каждого из них могут быть используемый различные резервные хранилища. Конкретный объект, относящийся к любой из этих категорий, называется файловым объектом. Другими общими терминами являются поток и файлоподобный объект.

Независимо от своей категории, каждый конкретный объект потока также будет иметь различные возможности: он может быть доступен только для чтения, только для записи или для чтения-записи. Он также может разрешать произвольный произвольный доступ (поиск прямого или обратного в любое местоположение) или только последовательный доступ (например, в случае сокет или пайп).

Все потоки внимательно относятся к типу данных, которые вы им даете. Например, предоставление объекта str методу write() двоичного потока вызовет TypeError. Так будет давать объект bytes методу write() текстового потока.

Изменено в версии 3.3: Операции, которые используемый поднять IOError сейчас поднимают OSError, так как IOError сейчас является алиас OSError.

Текстовый I/O

Текстовый I/O ожидает и производит объекты str. Это означает, что каждый раз, когда резервное хранилище изначально состоит из байтов (например, в случае файла), кодировка и декодирование данных выполняется прозрачно, а также необязательный перевод символов новой строки, специфичных для платформы.

Проще всего создать текстовый поток с помощью open(), опционально указывая кодировку:

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

Текстовые потоки в памяти также доступны как StringIO объекты:

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

Текстовый API потока описан подробно в документации TextIOBase.

Бинарный I/O

Двоичный I/O (также называемый буферизованый I/O) ожидает байтообразные объекты и производит объекты bytes. кодировка, декодирование или преобразование новой строки не выполняется. Эта категория потоков может быть используемый для всех видов нетекстовых данных, а также когда требуется ручное управление обработкой текстовых данных.

Самый простой способ создать двоичный поток - с помощью open() с 'b' в режиме строки:

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

Двоичные потоки в памяти также доступны в качестве объектов BytesIO:

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

Двоичный поток API подробно описан в документах BufferedIOBase.

Другие библиотечные модули могут обеспечивать дополнительные способы создания текстовых или двоичных потоков. См. socket.socket.makefile(), например.

Сырой I/O

Сырым I/O (также названный небуферизованный I/O) обычно используется как стандартный блок низкоуровневое для текстовых потоков и набора из двух предметов; редко бывает полезно непосредственно манипулировать сырьевым потоком от пользователя код. Тем не менее, можно создать необработанный поток, открыв файл в двоичном режиме с отключенной буферизацией:

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

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

Интерфейс модуля высокого уровня

io.DEFAULT_BUFFER_SIZE

int, содержащий размер буфера по умолчанию, используемый буферизованными классами I/O модуля. open() по возможности использует blksize файла (полученный методом os.stat()).

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

Это - алиас для встроенной функции open().

Эта функция вызывает событие аудита open с аргументами path, mode и flags. Аргументы mode и flags могли быть изменены или выведены из исходного вызова.

io.open_code(path)

Открывает предоставленный файл с режимом 'rb'. Эта функция должна быть используемый, когда цель состоит в том, чтобы считать содержимое исполняемым код.

path должен быть str и абсолютным путем.

Поведение этой функции может быть переопределено более ранним вызовом PyFile_SetOpenCodeHook(). Однако, предполагая, что path - это str и абсолютный путь, open_code(path) всегда должен вести себя так же, как open(path, 'rb'). Переопределение поведения предназначено для дополнительной проверки или предварительной обработки файла.

Добавлено в версии 3.8.

exception io.BlockingIOError

Это - совместимость алиас для встроенного исключения BlockingIOError.

exception io.UnsupportedOperation

Исключение, наследующее OSError и ValueError, которое возникает при вызове неподдерживаемой операции в потоке.

Потоки в памяти

Также можно использовать str или байтоподобный объект в качестве файла как для чтения, так и для записи. Для строки StringIO может быть используемый как файл, открытый в текстовом режиме. BytesIO может быть используемый, как файл, открытый в двоичном режиме. Оба обеспечивают полную возможность чтения-записи с произвольным доступом.

См.также

sys содержит стандартные потоки ввода-вывода: sys.stdin, sys.stdout и sys.stderr.

Иерархия классов

Реализация I/O потоков организована как иерархия классов. Первые абстрактный базовый класс (ABC), которые являются используемый, чтобы определить различные категории потоков, затем конкретные классы, обеспечивающие стандартные внедрения потока.

Примечание

Абстрактные базовые классы также обеспечивают реализацию некоторых методов по умолчанию, чтобы помочь реализации конкретных классов потоков. Например, BufferedIOBase обеспечивает неоптимизированные реализации readinto() и readline().

В верхней части иерархии I/O находится абстрактный базовый класс IOBase. Он определяет базовый интерфейс для потока. Однако следует отметить, что нет разделения между чтением и записью в потоки; реализации могут поднимать UnsupportedOperation, если они не поддерживают данную операцию.

RawIOBase ABC удлиняет IOBase. Он касается чтения и записи байтов в поток. FileIO подклассы RawIOBase для обеспечения интерфейса файлов в файловой системе машины.

BufferedIOBase ABC имеет дело с буферизованием на сыром потоке байта (RawIOBase). Его буферные потоки подклассы, BufferedWriter, BufferedReader и BufferedRWPair, доступные для чтения, записи и чтения и записи. BufferedRandom обеспечивает буферизованный интерфейс для потоков произвольного доступа. Другой BufferedIOBase подкласс, BytesIO, является потоком байтов в памяти.

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

Имена аргумента не часть спецификации, и только аргументы open() предназначены, чтобы быть используемый как аргументами ключевой.

Следующая таблица суммирует ABCs, обеспеченный io module:

ABC Наследуется Методы заглушки Методы и свойства миксины
IOBase   fileno, seek, and truncate close, closed, __enter__, __exit__, flush, isatty, __iter__, __next__, readable, readline, readlines, seekable, tell, writable, and writelines
RawIOBase IOBase readinto and write Inherited IOBase methods, read, and readall
BufferedIOBase IOBase detach, read, read1, and write Inherited IOBase methods, readinto, and readinto1
TextIOBase IOBase detach, read, readline, and write Inherited IOBase methods, encoding, errors, and newlines

Базовые классы I/O

class io.IOBase

Абстрактный базовый класс для всех классов I/O, действующих на потоки байтов. Отсутствует публичный конструктор.

Этот класс предоставляет пустые абстрактные реализации для многих методов, которые производные классы могут переопределять выборочно; реализации по умолчанию представляют файл, который невозможно прочитать, записать или просмотреть.

Даже если IOBase не объявляет read() или write(), поскольку их сигнатуры будут различаться, реализации и клиенты должны рассматривать эти методы как часть интерфейса. Кроме того, реализации могут вызывать ValueError (или UnsupportedOperation) при вызове операций, которые они не поддерживают.

Базовый тип используемый для двоичных данных, считываемых из файла или записываемых в файл, является bytes. Другие байтоподобные объекты также принимаются в качестве аргументов метода. Текст классы I/O работает с данными str.

Обратите внимание, что вызов любого метода (даже запросов) в закрытом потоке не определен. В этом случае реализации могут поднять ValueError.

IOBase (и его подклассы) поддерживает протокол итератора, означающий, что объект IOBase можно итерировать над получением строк в потоке. Линии определены немного по-другому в зависимости от того, является ли поток двойным потоком (приводящий к байтам) или текстовым потоком (приводящий к символ строки). См. readline() ниже.

IOBase также является менеджером контекст и поэтому поддерживает with инструкция. В этом примере, file закрывается после того, как набор 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()

Возвращает True если поток можно считывать из. Если False, read() поднимет OSError.

readline(size=-1)

Прочитать и возвращает одну строку из потока. Если параметр size указан, будет считано не более size байт.

Терминатор строки всегда является b'\n' для двоичных файлов; для текстовых файлов аргумент newline open() может быть используемый, чтобы выбрать признанного терминатора (терминаторов) линии.

readlines(hint=-1)

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

Обратите внимание, что итерация объектов файла с помощью метода for line in file: ... уже возможна без вызова метода file.readlines().

seek(offset, whence=SEEK_SET)

Измените позицию потока на заданный байт offset. offset интерпретируется относительно положения, обозначенного как whence. Дефолт значение для whence является SEEK_SET. Значения для whence:

  • SEEK_SET или 0 - начало потока (по умолчанию); offset должно быть нулевым или положительным
  • SEEK_CUR или 1 - текущее положение потока; offset может быть отрицательным
  • SEEK_END или 2 - конец потока; offset обычно отрицательный

Возвращает новое абсолютное положение.

Добавлено в версии 3.1: Константы SEEK_*.

Добавлено в версии 3.3: Некоторые операционные системы могут поддерживать дополнительные значения, такие как os.SEEK_HOLE или os.SEEK_DATA. Допустимая значения для файла может зависеть от того, открыт ли он в текстовом или двоичном режиме.

seekable()

Возвращает True если поток поддерживает произвольный доступ. Если False, seek(), tell() и truncate() поднимет OSError.

tell()

Возвращает текущую позицию потока.

truncate(size=None)

Измените размеры потока к данному size в байтах (или текущее положение, если size не определен). Текущее положение потока не изменено. Это изменение размера может увеличить или уменьшить текущий размер файла. В случае расширения содержимое новой файловой области зависит от платформы (в большинстве систем дополнительные байты заполняются нулем). Новый размер файла равен возвращенный.

Изменено в версии 3.5: Теперь Windows будет заполнять файлы при расширении.

writable()

Возвращает True если поток поддерживает запись. Если False, write() и truncate() поднимет OSError.

writelines(lines)

Записать список строк в поток. Сепараторы строк не добавляются, поэтому обычно для каждой из линий предусмотрен сепаратор на конце.

__del__()

Подготовьтесь к уничтожению объекта. IOBase обеспечивает внедрение по умолчанию этого метода, который называет метод сущность close().

class io.RawIOBase

Базовый класс для необработанных двоичных I/O. Он наследует IOBase. Отсутствует публичный конструктор.

Сырой двоичный I/O, как правило, обеспечивает доступ низкоуровневое к основному устройству OS или API, и не пытается заключить в капсулу его в примитивах высокого уровня (это оставляют буферизированному I/O и тексту I/O, описал позже на этой странице).

Кроме атрибуты и методов из IOBase, RawIOBase предоставляет следующие методы:

read(size=-1)

Считывание до size байт из объекта и их возвращает. Для удобства, если size не указан или -1, все байты до EOF будут возвращенный. В противном случае выполняется только один системный вызов. Меньше, чем байты size могут быть возвращенный если требование операционной системы возвращает меньше, чем байты size.

Если 0 байт равно возвращенный, а size не 0, это означает конец файла. Если объект находится в неблокирующем режиме и нет доступных байтов, None является возвращенный.

Реализация по умолчанию откладывается на readall() и readinto().

readall()

Считывание и возвращает всех байтов из потока до EOF с использованием при необходимости нескольких вызовов потока.

readinto(b)

Прочитать байты в предварительно ассигнованный, перезаписываемый байтоподобным объектом b и возвращает число прочитанных байтов. Например, b может быть bytearray. Если объект находится в неблокирующем режиме и нет доступных байтов, None является возвращенный.

write(b)

Записать переданный байтоподобный объект, b в базовый исходный поток и возвращает число записанных байтов. Это может быть меньше длины b в байтах, в зависимости от специфики базового исходного потока, и особенно если он находится в неблокирующем режиме. None является возвращенный, если исходный поток установлен не блокировать и в него не может быть легко записан один байт. Посетитель может выпустить или видоизменить b после этого метода возвращает, таким образом, внедрение должно только получить доступ к b во время требования метода.

class io.BufferedIOBase

Базовый класс для двоичных потоков, поддерживающих какую-либо буферизацию. Он наследует IOBase. Отсутствует конструктор public.

Главное отличие от RawIOBase заключается в том, что методы read(), readinto() и write() будут пытаться (соответственно) считывать столько входных данных, сколько требуется, или потреблять все заданные выходные данные за счет выполнения, возможно, нескольких системных вызовов.

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

Кроме того, метод read() не имеет реализации по умолчанию, которая откладывает на readinto().

Типичная реализация BufferedIOBase должна наследовать не от реализации RawIOBase, а сворачивать, как BufferedWriter и BufferedReader do.

BufferedIOBase предоставляет или отвергает эти методы и атрибут в дополнение к методам от IOBase:

raw

Базовый исходный поток (сущность RawIOBase), с которым BufferedIOBase имеет дело. Это не является частью API BufferedIOBase и может отсутствовать в некоторых реализациях.

detach()

Отделите исходный поток от буфера и возвращает его.

После отделения исходного потока буфер находится в непригодном для использования состояние.

У некоторых буферов, как BytesIO, нет понятия единственного сырого потока к возвращает из этого метода. Они поднимают UnsupportedOperation.

Добавлено в версии 3.1.

read(size=-1)

Чтение и возвращает до size байт. Если аргумент опущен, None или отрицателен, данные считываются и возвращенный до достижения EOF. Пустой объект bytes - возвращенный, если поток уже в EOF.

Если аргумент положительный, и базовый исходный поток не является интерактивным, может быть выдано несколько необработанных считываний, чтобы удовлетворить счетчику байтов (если не достигнут EOF первым). Но для интерактивных необработанных потоков будет выпущено максимум одно необработанное чтение, и короткий результат не предполагает, что EOF неизбежен.

BlockingIOError поднят, если основной сырой поток находится в не режим блокирования и не имеет никаких доступных данных в данный момент.

read1([size])

Чтение и возвращает до size байт, причем не более одного вызова метода read() (или readinto()) базового исходного потока. Это может быть полезно при реализации собственной буферизации поверх объекта BufferedIOBase.

Если size равно -1 (по умолчанию), произвольное число байт равно возвращенный (больше нуля, если не достигнуто значение EOF).

readinto(b)

Прочитать байты в предварительно ассигнованный, перезаписываемый байтоподобный объект b и возвращает число прочитанных байтов. Например, b может быть bytearray.

Как и read(), множество считываний может быть выдано базовому исходному потоку, если последний не является интерактивным.

BlockingIOError поднят, если основной сырой поток находится в не режим блокирования и не имеет никаких доступных данных в данный момент.

readinto1(b)

Считывание байтов в предварительно выделенные, доступные для записи байтоподобного объекта b с использованием не более одного вызова метода read() (или readinto()) базового исходного потока. Возвращает число считанных байтов.

BlockingIOError поднят, если основной сырой поток находится в не режим блокирования и не имеет никаких доступных данных в данный момент.

Добавлено в версии 3.5.

write(b)

Записать переданный байтоподобный объект, b и возвращает количество записанных байтов (всегда равно длине b в байтах, так как в случае неудачи записи поднимется OSError). В зависимости от фактической реализации эти байты могут быть легко записаны в базовый поток или сохранены в буфере по причинам производительности и задержки.

Когда в неблокировании режима, BlockingIOError поднят, если данные должны были быть написаны сырому потоку, но это не могло бы принять все данные без блокирования.

Посетитель может выпустить или видоизменить b после этого метода возвращает, таким образом, внедрение должно только получить доступ к b во время требования метода.

Сырой файловый I/O

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

FileIO представляет файл уровня оС, содержащий байты данных. Он реализует интерфейс RawIOBase (и, следовательно, интерфейс IOBase).

name может быть одним из двух things:

  • объект символ строка или bytes, представляющий путь к файлу, который будет открыт. В этом случае closefd должен быть True (по умолчанию), в противном случае возникает ошибка.
  • целое число, представляющее номер существующего файла уровня оС дескриптор, к которому будет предоставлен доступ результирующему объекту FileIO. Когда объект FileIO будет закрыт, этот fd будет закрыт также, если closefd не установлен в False.

mode может быть 'r', 'w', 'x' или 'a' для чтения (по умолчанию), записи, монопольного создания или добавления. Файл будет создан, если он не существует при открытии для записи или добавления; он будет усечен при открытии для записи. FileExistsError будет поднят, если он уже существует при открытии для создания. Открытие файла для создания подразумевает запись, поэтому этот режим ведет себя аналогично 'w'. Добавьте '+' в режим, чтобы разрешить одновременное чтение и запись.

Методы read() (при вызове с положительным аргументом), readinto() и write() в этом классе будут выполнять только один системный вызов.

Пользовательское начало может быть используемый, передав подлежащее вызову как opener. Лежащий в основе файл дескриптор для объекта файла затем получается путем вызова метода opener с помощью (name, flags). opener должен возвращает открытый файл дескриптор (передача os.open как opener приводит к функциональности, аналогичной передаче None).

Созданный файл будет non-inheritable.

Примеры использования параметра open() см. в встроенной функции opener.

Изменено в версии 3.3: Добавлен параметр opener. Добавлен режим 'x'.

Изменено в версии 3.4: Теперь файл не наследуется.

В дополнение к атрибуты и методам из IOBase и RawIOBase, FileIO предоставляет следующие данные атрибуты:

mode

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

name

Имя файла. Это файл дескриптор файла, если в конструкторе не указано имя.

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

Буферизованные потоки I/O предоставляют высокоуровневый интерфейс устройству I/O, чем сырой I/O.

class io.BytesIO([initial_bytes])

Реализация потока с использованием буфера в байтах памяти. Он наследует BufferedIOBase. Буфер отбрасывается при вызове метода close().

Необязательный аргумент initial_bytes - это байтоподобный объект, содержащий начальные данные.

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])

В BytesIO это то же самое, что и read().

Изменено в версии 3.7: Аргумент size теперь необязателен.

readinto1(b)

В BytesIO это то же самое, что и readinto().

Добавлено в версии 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буфер, обеспечивающий доступ более высокого уровня к считываемому последовательному объекту RawIOBase. Он наследует BufferedIOBase. При считывании данных из этого объекта больший объем данных может быть запрошен из базового исходного потока и сохранен во внутреннем буфере. Буферизованные данные затем могут быть возвращенный непосредственно при последующих считываниях.

Конструктор создает BufferedReader для данного считываемого raw потока и buffer_size. Если значение buffer_size опущено, значение DEFAULT_BUFFER_SIZE равно используемый.

BufferedReader предоставляет или переопределяет эти методы в дополнение к методам из BufferedIOBase и IOBase:

peek([size])

Возвращает байтов из потока без продвижения позиции. Для удовлетворения вызова выполняется самое большее одно считывание в исходном потоке. Число байтов возвращенный может быть меньше или больше запрошенного.

read([size])

Считывание и возвращает size байт, или если size не задан или отрицательный, до EOF или если вызов чтения будет заблокирован в неблокирующем режиме.

read1([size])

Чтение и возвращает до size байт с одним вызовом в исходном потоке. Если буферизован хотя бы один байт, то возвращенный только буферизованные байты. В противном случае выполняется один вызов считывания необработанного потока.

Изменено в версии 3.7: Аргумент size теперь необязателен.

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буфер, обеспечивающий доступ более высокого уровня к записываемому последовательному объекту RawIOBase. Он наследует BufferedIOBase. При записи в этот объект данные обычно помещаются во внутренний буфер. Буфер будет записан в нижележащий объект RawIOBase при различных условиях, включая:

  • когда буфер становится слишком маленьким для всех ожидающих данных;
  • при вызове flush();
  • когда запрашивается seek() (для объектов BufferedRandom);
  • когда объект BufferedWriter закрыт или разрушен.

Конструктор создает BufferedWriter для данного записываемого потока raw. Если buffer_size не дан, он не выполняет своих обязательств к DEFAULT_BUFFER_SIZE.

BufferedWriter предоставляет или переопределяет эти методы в дополнение к методам из BufferedIOBase и IOBase:

flush()

Принудительно поместить байты, хранящиеся в буфере, в исходный поток. BlockingIOError должен быть поднят, если сырой поток блокирует.

write(b)

Записать байтоподобный объект, b и возвращает число записанных байтов. Если буфер должен быть записан, то в неблокирующем режиме поднимается BlockingIOError, а необработанный поток блокируется.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

Буферизованный интерфейс для потоков произвольного доступа. Она наследует BufferedReader и BufferedWriter.

Конструктор создает устройство чтения и записи для искомого исходного потока, указанного в первом аргументе. Если buffer_size опущен, по умолчанию устанавливается значение DEFAULT_BUFFER_SIZE.

BufferedRandom способен на все BufferedReader или BufferedWriter может сделать. Кроме того, гарантировано осуществление seek() и tell().

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

Буферизованный объект I/O, объединяющий два однонаправленных объекта RawIOBase - один читаемый, другой записываемый - в одну двунаправленную конечную точку. Он наследует BufferedIOBase.

reader и writer - объекты RawIOBase, которые являются удобочитаемыми и writeable соответственно. Если buffer_size опущен, по умолчанию устанавливается значение DEFAULT_BUFFER_SIZE.

BufferedRWPair реализует все методы BufferedIOBase, кроме detach(), что вызывает UnsupportedOperation.

Предупреждение

BufferedRWPair не пытается синхронизировать доступ к основным исходным потокам. Не следует передавать ему тот же объект, что и программе чтения и записи; вместо этого используйте BufferedRandom.

Текстовый I/O

class io.TextIOBase

Базовый класс для текстовых потоков. Этот класс обеспечивает символ и основанный на линии интерфейс, чтобы течь I/O. Он наследует IOBase. Отсутствует конструктор public.

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)

Чтение до новой строки или EOF и возвращает одного str. Если поток уже в EOF, пустой строка - возвращенный.

Если указан параметр size, будет прочитано не более size символов.

seek(offset, whence=SEEK_SET)

Смените положение потока к данному offset. Поведение зависит от параметра whence. Дефолт значение для whence является SEEK_SET.

  • SEEK_SET или 0: искать с начала потока (по умолчанию); offset должно быть числом возвращенный по TextIOBase.tell() или нулевым. Любой другой offset значение производит неопределенное поведение.
  • SEEK_CUR или 1: «искать» на текущую должность; offset должен быть равен нулю, что является бездействием (все остальные значения не поддерживаются).
  • SEEK_END или 2: искать до конца потока; offset должен быть равен нулю (все остальные значения не поддерживаются).

Возвращает новую абсолютную позицию как непрозрачное число.

Добавлено в версии 3.1: Константы SEEK_*.

tell()

Возвращает текущее положение потока как непрозрачное число. Число обычно не представляет число байтов в базовом двоичном хранилище.

write(s)

Записать строка s в поток и возвращает количество записанных символов.

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

Буферизованный текстовый поток через двоичный поток BufferedIOBase. Он наследует TextIOBase.

encoding задает имя кодировка, с которым будет декодирован или кодированный поток. По умолчанию используется значение locale.getpreferredencoding(False).

errors является необязательным строка, который определяет, как должны обрабатываться ошибки кодировка и декодирования. Передайте 'strict', чтобы поднять исключение ValueError, если есть ошибка кодировка (дефолт None имеет тот же эффект), или проход 'ignore', чтобы проигнорировать ошибки. (Обратите внимание, что игнорирование ошибок кодировка может привести к потере данных.) 'replace' вызывает вставку маркера замены (например, '?') в случае неправильного формирования данных. 'backslashreplace' приводит к замене неверно сформированных данных последовательностью побега с обратной отсечкой. Сочиняя, 'xmlcharrefreplace' (заменяют соответствующей ссылкой XML символ) или 'namereplace' (заменяют последовательностями побега \N{...}) могут быть используемый. Любое другое имя обработки ошибок, зарегистрированное в codecs.register_error(), также является допустимым.

newline управляет обработкой окончаний строк. Это могут быть None, '', '\n', '\r' и '\r\n'. Работает следующим образом:

  • При чтении входных данных из потока, если newline является None, включается режим универсальный символ новой строки. Линии во входе могут закончиться в '\n', '\r' или '\r\n', и они переведены на '\n' перед стать возвращенный посетителю. Если это - '', универсальный newlines режим включен, но окончания линии - возвращенный непереведенному посетителю. Если у этого есть какой-либо из других юридических значения, входные линии только закончены данным строка, и окончание линии - возвращенный непереведенному посетителю.
  • При записи выходных данных в поток, если newline является None, любые записанные символы '\n' переводятся в системный разделитель строк по умолчанию, os.linesep. Если newline является '' или '\n', перевод не выполняется. Если newline является какой-либо из других юридических значения, любые написанные символы '\n' переводятся на данный строка.

Если line_buffering является True, то flush() подразумевается, когда вызов для записи содержит новую строку символ или каретку возвращает.

Если write_through является True, вызовы write() гарантированно не буферизуются: любые данные, записанные на объекте TextIOWrapper, немедленно обрабатываются в лежащем в их основе двоичном buffer.

Изменено в версии 3.3: Аргумент write_through добавлен.

Изменено в версии 3.3: Дефолтом encoding является теперь locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Не изменяйтесь временный место действия кодировка, используя locale.setlocale(), используйте текущее место действия, кодировка вместо пользователя предпочел кодировка.

TextIOWrapper предоставляет этих членов в дополнение к членам TextIOBase и его родителей:

line_buffering

Активизирована ли буферизация строк.

write_through

Передается ли запись немедленно в базовый двоичный буфер.

Добавлено в версии 3.7.

reconfigure(*[, encoding][, errors][, newline][, line_buffering][, write_through])

Перенастроите этот текстовый поток с помощью новых параметров для encoding, errors, newline, line_buffering и write_through.

Параметры, не определенные, держат параметры настройки в курсе, кроме errors='strict' используемый, когда encoding определен, но errors не определен.

Невозможно изменить кодировка или новую строку, если некоторые данные уже считаны из потока. С другой стороны, возможно изменение кодировка после записи.

Этот метод выполняет неявную очистку потока перед установкой новых параметров.

Добавлено в версии 3.7.

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

Поток в памяти для текста I/O. Текстовый буфер отбрасывается при вызове метода close().

Начальный значение буфера может быть установлен, обеспечив initial_value. Если перевод новой строки включен, то новые строки будут кодированный как бы по write(). Поток позиционируется в начале буфера.

Аргумент newline работает как аргумент TextIOWrapper. По умолчанию в качестве концов строк используются только символы \n и перевод новых строк не выполняется. Если newline установлен в None, newlines написаны как \n на всех платформах, но универсальная расшифровка newline все еще выполнена, читая.

StringIO предоставляет этот метод в дополнение к методам от TextIOBase и его родителей:

getvalue()

Возвращает str, содержащий все содержимое буфера. Новые строки декодируются как бы по read(), хотя положение потока не изменяется.

Использование в качестве примера:

import io

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

# Получить содержимое файла - это будет
# 'Первая строка.\nВторая строка.\n'
contents = output.getvalue()

# Закрытие объекта и удаление буфера памяти.
# getvalue() вызовет исключение.
output.close()
class io.IncrementalNewlineDecoder

Кодировка помощника, который расшифровывает newlines для режима универсальный символ новой строки. Он наследует codecs.IncrementalDecoder.

Исполнение

В этом разделе рассматриваются выполнение обеспеченных конкретных внедрений I/O.

Бинарный I/O

Читая и сочиняя только большой чанки данных, даже когда пользователь просит единственный байт, буферизованный I/O скрывает любую неэффективность в запросе и выполнении небуферизированного распорядка операционной системы I/O. Выгода зависит от OS и вида I/O, который выполнен. Например, на некоторых современных Ose, таких как Linux, небуферизированный диск I/O может быть с такой скоростью, как буферизован I/O. Итог, однако, то, который буферизовал предсказуемое исполнение предложений I/O независимо от платформы и отступающего устройства. Поэтому почти всегда предпочтительно использовать буферизованные I/O, а не небуферизованные I/O для двоичных данных.

Текстовый I/O

Текстовый I/O по двойному месту хранения (такому как файл) значительно медленнее, чем двоичный I/O по тому же месту хранения, потому что это требует преобразований между Юникодом и двоичными данными, используя символ кодировка. Это может стать заметной обработкой огромных объемов текстовых данных, таких как большие файлы журнала. Также TextIOWrapper.tell() и TextIOWrapper.seek() - оба довольно медленные из-за алгоритма реконструкции используемый.

StringIO, однако, является собственным контейнером юникод в памяти и будет демонстрировать скорость, аналогичную скорости BytesIO.

Мультипронизывание

Объекты FileIO поток-безопасны до такой степени, что операционная система звонит (такие как read(2) под Unix), они обертывают, поток-безопасны также.

Двоичные буферизированные объекты (сущности BufferedReader, BufferedWriter, BufferedRandom и BufferedRWPair) защищают свои внутренние структуры с помощью блокировки; поэтому можно с уверенностью звонить им сразу из нескольких потоки.

TextIOWrapper объекты не являются потокобезопасной.

Повторная входимость

Двоичные буферизированные объекты (сущности из BufferedReader, BufferedWriter, BufferedRandom и BufferedRWPair) не поступают повторно. В то время как требований reentrant не произойдет в нормальных ситуациях, они могут явиться результатом выполнения I/O в обработчике signal. Если поток пытается повторно войти в буферизированный объект, к которому он уже получает доступ, RuntimeError поднят. Обратите внимание, что это не запрещает другому поток входить в буферизованный объект.

Вышеупомянутое неявно распространяется на текстовые файлы, так как функция open() обернет буферизированный объект в TextIOWrapper. Это включает стандартные потоки и, следовательно, влияет также на встроенную функцию print().