open ()

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

Открывает файл file и возвращает соответствующий файловый объект. Если файл не открывается, возникает ошибка OSError. См. дополнительные примеры использования этой функции в разделе «Чтение и запись файлов».

file - это объект, похожий на путь, задающий имя пути (абсолютное или относительное к текущему рабочему каталогу) открываемого файла или целочисленный файловый дескриптор файла, который нужно обернуть. (Если указан файловый дескриптор, он закрывается при закрытии возвращенного объекта ввода-вывода, если для closefd не задано значение False.)

mode - необязательная строка, указывающая режим, в котором открывается файл. По умолчанию это 'r', что означает открытие для чтения в текстовом режиме. Другими распространенными значениями являются 'w' для записи (удаляет содержимое файла, если он уже существует), 'x' для исключительного создания и 'a' для добавления (что в некоторых системах Unix означает, что все записи добавляются в конец файла независимо от текущей позиции поиска). В текстовом режиме, если кодировка не указана, используемая кодировка зависит от платформы: locale.getpreferredencoding (False) вызывается для получения текущей кодировки языкового стандарта. (Для чтения и записи сырых байтов используйте двоичный режим и не указывайте кодировку.) Доступны следующие режимы:

Символ mode	Значение
'r'	открыть для чтения (по умолчанию)
'w'	открыть для записи, удалить содержимое файла
'x'	открыть для монопольного создания, сбой, если файл уже существует
'a'	открыть для записи, добавить в конец файла, если он существует
'b'	двоичный режим
't'	текстовый режим (по умолчанию)
'+'	открыть для обновления (чтение и запись)

Режим по умолчанию - 'r' (открыть для чтения текста, синоним 'rt'). Режимы 'w+' и 'w+b' открывают и обрезают файл. Режимы 'r +' и 'r+b' открывают файл без усечения.

Как упоминалось в обзоре, Python различает двоичный и текстовый ввод-вывод. Файлы, открытые в двоичном режиме (включают аргумент 'b' режима), возвращают содержимое как байтовые объекты без какого-либо декодирования. В текстовом режиме (по умолчанию или когда включен аргумент режима 't') содержимое файла возвращается как строка str, байты были сначала декодированы с использованием зависящей от платформы кодировки или с использованием указанной кодировки encoding, если она задана.

Разрешен дополнительный символ режима 'U', который больше не действует и считается устаревшим. Ранее он включал универсальные символы новой строки в текстовом режиме, который стал поведением по умолчанию в Python 3.0. Обратитесь к документации параметра новой строки для получения дополнительных сведений.

Python не зависит от представления текстовых файлов базовой операционной системой; вся обработка выполняется самим Python и поэтому не зависит от платформы.

buffering - необязательное целое число, используемое для установки политики буферизации. Передайте 0, чтобы отключить буферизацию (разрешено только в двоичном режиме), 1, чтобы выбрать построчную буферизацию (можно использовать только в текстовом режиме), и целое число > 1, чтобы указать размер в байтах буфера фрагментов фиксированного размера. Если аргумент buffering не указан, политика буферизации по умолчанию работает следующим образом:

• двоичные файлы буферизуются кусками фиксированного размера; размер буфера выбирается с помощью эвристики, пытающейся определить «размер блока» нижележащего устройства и возвращаясь к io.DEFAULT_BUFFER_SIZE. Во многих системах размер буфера обычно составляет 4096 или 8192 байта.

• «интерактивные» текстовые файлы (файлы, для которых isatty () возвращает True) используют буферизацию строк. Другие текстовые файлы используют политику, описанную выше для двоичных файлов.

encoding - это имя кодировки, используемой для декодирования или кодирования файла. Это следует использовать только в текстовом режиме. Кодировка по умолчанию зависит от платформы (независимо от того, что возвращает locale.getpreferredencoding ()), но можно использовать любую кодировку текста, поддерживаемую Python. См. модуль codecs для получения списка поддерживаемых кодировок.

errors - это необязательная строка, указывающая, как должны обрабатываться ошибки кодирования и декодирования - это не может использоваться в двоичном режиме. Доступны различные стандартные обработчики ошибок (перечислены в разделе «Обработчики ошибок»), хотя любое имя обработки ошибок, зарегистрированное с помощью codecs.register_error (), также является допустимым. Стандартные названия включают:

• 'strict', чтобы вызвать исключение ValueError в случае ошибки кодирования. Значение по умолчанию None имеет тот же эффект

• 'ignore' игнорирует ошибки. Обратите внимание, что игнорирование ошибок кодирования может привести к потере данных

• 'replace' вызывает вставку маркера замены (например, '?') там, где есть искаженные данные

• 'surrogateescape' будет представлять любые неправильные байты как кодовые точки в области частного использования Unicode в диапазоне от U+DC80 до U+DCFF. Эти частные кодовые точки затем будут преобразованы обратно в те же байты, когда при записи данных используется обработчик ошибок surrogateescape. Это полезно для обработки файлов в неизвестной кодировке

• 'xmlcharrefreplace' поддерживается только при записи в файл. Символы, не поддерживаемые кодировкой, заменяются соответствующей ссылкой на символ XML &#nnn;

• 'backslashreplace' заменяет искаженные данные escape-последовательностями Python с обратной косой чертой

• 'namereplace' (также поддерживается только при записи) заменяет неподдерживаемые символы escape-последовательностями \N{...}

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

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

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

Если closefd имеет значение False и был задан дескриптор файла, а не имя файла, базовый дескриптор файла будет оставаться открытым при закрытии файла. Если указано имя файла, closefd должен иметь значение True (по умолчанию), в противном случае возникнет ошибка.

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

Вновь созданный файл не наследуется.

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

>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
...     return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
...     print('This will be written to somedir/spamspam.txt', file=f)
...
>>> os.close(dir_fd)  # don't leak a file descriptor

Тип файлового объекта, возвращаемого функцией open (), зависит от режима. Когда open () используется для открытия файла в текстовом режиме ('w', 'r', 'wt', 'rt' и т. д.), Он возвращает подкласс io.TextIOBase (в частности, io.TextIOWrapper). При использовании для открытия файла в двоичном режиме с буферизацией возвращаемый класс является подклассом io.BufferedIOBase. Точный класс варьируется: в двоичном режиме чтения он возвращает io.BufferedReader; в двоичных режимах записи и добавления двоичных файлов он возвращает io.BufferedWriter, а в режиме чтения/записи возвращает io.BufferedRandom. Когда буферизация отключена, возвращается необработанный поток, подкласс io.RawIOBase, io.FileIO.

См. также модули обработки файлов, такие как fileinput, io (где объявлен open ()), os, os.path, tempfile и shutil.

Вызывает событие аудита open с аргументами file, mode, flags.

Аргументы mode и flags могли быть изменены или выведены из исходного вызова.

Изменено в версии 3.3:

• добавлен параметр opener

• добавлен режим 'x'

• раньше вызывалась ошибка IOError, теперь это псевдоним OSError

• FileExistsError теперь возникает, если файл, открытый в монопольном режиме создания ('x'), уже существует.

Изменено в версии 3.4:

• теперь файл не наследуется

Устарело с версии 3.4, будет удалено в версии 3.9: режим 'U'.

Изменено в версии 3.5:

• если системный вызов прерывается и обработчик сигнала не вызывает исключения, функция теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (объяснение см. в PEP 475).

• добавлен обработчик ошибок 'namereplace'

Изменено в версии 3.6:

• добавлена поддержка для принятия объектов, реализующих os.PathLike

• в Windows открытие консольного буфера может вернуть подкласс io.RawIOBase, отличный от io.FileIO