tempfile — Создание временных файлов и каталогов¶

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

Этот модуль создает временные файлы и каталоги. Он работает на всех поддерживаемых платформах. TemporaryFile, NamedTemporaryFile, TemporaryDirectory и SpooledTemporaryFile - это высокоуровневые интерфейсы, которые обеспечивают автоматическую очистку и могут использоваться в качестве менеджеров контекста. mkstemp() и mkdtemp() - это функции более низкого уровня, которые требуют ручной очистки.

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

Модуль определяет следующие вызываемые пользователем элементы:

tempfile.TemporaryFile(mode='w+b', buffering=- 1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)¶

Возвращает file-like object, который может быть использован в качестве временной области хранения. Файл создается безопасно, с использованием тех же правил, что и mkstemp(). Он будет уничтожен, как только будет закрыт (включая неявное закрытие при сборке мусора). В Unix запись каталога для файла либо не создается вообще, либо удаляется сразу после создания файла. Другие платформы этого не поддерживают; ваш код не должен полагаться на то, что временный файл, созданный с помощью этой функции, имеет или не имеет видимое имя в файловой системе.

Полученный объект можно использовать в качестве менеджера контекста (см. Примеры). При завершении контекста или уничтожении объекта файла временный файл будет удален из файловой системы.

Параметр mode по умолчанию имеет значение 'w+b', чтобы созданный файл можно было читать и записывать без закрытия. Двоичный режим используется для того, чтобы файл вел себя одинаково на всех платформах без учета хранимых данных. буферизация, кодирование, ошибки и новая строка интерпретируются как для open().

Параметры dir, prefix и suffix имеют то же значение и значения по умолчанию, что и для mkstemp().

Возвращаемый объект является истинным файловым объектом на платформах POSIX. На других платформах это файлоподобный объект, чей атрибут file является базовым истинным файловым объектом.

Флаг os.O_TMPFILE используется, если он доступен и работает (специфично для Linux, требуется ядро Linux 3.11 или более поздняя версия).

На платформах, которые не являются ни Posix, ни Cygwin, TemporaryFile является псевдонимом для NamedTemporaryFile.

Вызывает auditing event tempfile.mkstemp с аргументом fullpath.

Изменено в версии 3.5: Флаг os.O_TMPFILE теперь используется, если он доступен.

Изменено в версии 3.8: Добавлен параметр ошибки.

tempfile.NamedTemporaryFile(mode='w+b', buffering=- 1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None)¶

Эта функция работает точно так же, как и TemporaryFile(), за исключением того, что файл гарантированно имеет видимое имя в файловой системе (в Unix запись в каталоге не является несвязанной). Это имя можно получить из атрибута name возвращаемого файлоподобного объекта. Можно ли использовать это имя для открытия файла во второй раз, пока именованный временный файл все еще открыт, зависит от платформы (на Unix можно использовать это имя, на Windows - нет). Если delete равно true (по умолчанию), файл удаляется сразу после его закрытия. Возвращаемый объект всегда является файлоподобным объектом, чей атрибут file является базовым истинным файловым объектом. Этот файлоподобный объект можно использовать в операторе with, как и обычный файл.

Вызывает auditing event tempfile.mkstemp с аргументом fullpath.

Изменено в версии 3.8: Добавлен параметр ошибки.

class tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=- 1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)¶

Этот класс работает точно так же, как TemporaryFile(), за исключением того, что данные хранятся в памяти, пока размер файла не превысит max_size, или пока не будет вызван метод fileno() файла, после чего содержимое записывается на диск и работа продолжается, как в случае TemporaryFile().

Результирующий файл имеет один дополнительный метод rollover(), который заставляет файл перевернуться в файл на диске независимо от его размера.

Возвращаемый объект представляет собой файлоподобный объект, атрибутом которого _file является либо объект io.BytesIO или io.TextIOWrapper (в зависимости от того, был ли указан двоичный или текстовый режим), либо истинный файловый объект, в зависимости от того, был ли вызван rollover(). Этот файлоподобный объект может быть использован в операторе with, как и обычный файл.

Изменено в версии 3.3: метод truncate теперь принимает аргумент size.

Изменено в версии 3.8: Добавлен параметр ошибки.

class tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False)¶

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

Имя каталога может быть получено из атрибута name возвращаемого объекта. Когда возвращаемый объект используется в качестве менеджера контекста, name будет присвоен целевому элементу as в операторе with, если таковой имеется.

Каталог можно явно очистить, вызвав метод cleanup(). Если ignore_cleanup_errors равно true, то любые необработанные исключения во время явной или неявной очистки (например, PermissionError при удалении открытых файлов в Windows) будут проигнорированы, а оставшиеся удаляемые элементы удалены по принципу «из последних сил». В противном случае, ошибки будут возникать в любом контексте очистки (вызов cleanup(), выход из контекстного менеджера, когда объект собирается в мусор или при завершении работы интерпретатора).

Вызывает auditing event tempfile.mkdtemp с аргументом fullpath.

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

Изменено в версии 3.10: Добавлен параметр ignore_cleanup_errors.

tempfile.mkstemp(suffix=None, prefix=None, dir=None, text=False)¶

Создает временный файл наиболее безопасным способом. При создании файла отсутствуют условия гонки, предполагая, что платформа правильно реализует флаг os.O_EXCL для os.open(). Файл доступен для чтения и записи только создающему идентификатору пользователя. Если платформа использует биты разрешения, чтобы указать, является ли файл исполняемым, файл не может быть исполнен никем. Дескриптор файла не наследуется дочерними процессами.

В отличие от TemporaryFile(), пользователь mkstemp() несет ответственность за удаление временного файла после завершения работы с ним.

Если suffix не None, имя файла будет заканчиваться этим суффиксом, в противном случае суффикса не будет. mkstemp() не ставит точку между именем файла и суффиксом; если она нужна, поставьте ее в начале suffix.

Если prefix не является None, имя файла будет начинаться с этого префикса; в противном случае используется префикс по умолчанию. По умолчанию возвращается значение gettempprefix() или gettempprefixb(), в зависимости от ситуации.

Если dir не является None, файл будет создан в этом каталоге; в противном случае используется каталог по умолчанию. Каталог по умолчанию выбирается из списка, зависящего от платформы, но пользователь приложения может контролировать расположение каталога, задавая переменные окружения TMPDIR, TEMP или TMP. Таким образом, нет гарантии, что сгенерированное имя файла будет обладать какими-либо приятными свойствами, например, не будет требовать кавычек при передаче внешним командам через os.popen().

Если любой из suffix, prefix и dir не None, они должны быть одного типа. Если они являются байтами, возвращаемое имя будет байтом, а не str. Если вы хотите принудительно вернуть байтовое значение, иначе поведение по умолчанию, передайте suffix=b''.

Если указано text и значение true, файл открывается в текстовом режиме. В противном случае (по умолчанию) файл открывается в двоичном режиме.

mkstemp() возвращает кортеж, содержащий хэндл уровня ОС к открытому файлу (как было бы возвращено os.open()) и абсолютное имя пути к этому файлу, в таком порядке.

Вызывает auditing event tempfile.mkstemp с аргументом fullpath.

Изменено в версии 3.5: Теперь suffix, prefix и dir могут быть переданы в байтах, чтобы получить байтовое возвращаемое значение. До этого разрешалось использовать только str. suffix и prefix теперь принимают и значение по умолчанию None, чтобы вызвать использование соответствующего значения по умолчанию.

Изменено в версии 3.6: Параметр dir теперь принимает значение path-like object.

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)¶

Создает временный каталог наиболее безопасным способом. При создании каталога отсутствуют условия гонки. Каталог доступен для чтения, записи и поиска только для создающего его пользователя.

Пользователь mkdtemp() отвечает за удаление временного каталога и его содержимого после завершения работы с ним.

Аргументы prefix, suffix и dir такие же, как и для mkstemp().

mkdtemp() возвращает абсолютное имя пути к новому каталогу.

Вызывает auditing event tempfile.mkdtemp с аргументом fullpath.

Изменено в версии 3.5: Теперь suffix, prefix и dir могут быть переданы в байтах, чтобы получить байтовое возвращаемое значение. До этого разрешалось использовать только str. suffix и prefix теперь принимают и значение по умолчанию None, чтобы вызвать использование соответствующего значения по умолчанию.

Изменено в версии 3.6: Параметр dir теперь принимает значение path-like object.

tempfile.gettempdir()¶

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

Python просматривает стандартный список каталогов, чтобы найти тот, в котором вызывающий пользователь может создавать файлы. Список выглядит следующим образом:

1. Каталог, названный переменной окружения TMPDIR.

2. Каталог, названный переменной окружения TEMP.

3. Каталог, названный переменной окружения TMP.

4. Расположение, специфичное для конкретной платформы:

   • В Windows - каталоги C:\TEMP, C:\TMP, \TEMP и \TMP, в таком порядке.

   • На всех остальных платформах - каталоги /tmp, /var/tmp и /usr/tmp, в таком порядке.

5. В крайнем случае, текущий рабочий каталог.

Результат этого поиска кэшируется, см. описание tempdir ниже.

Изменено в версии 3.10: Всегда возвращает строку. Ранее он возвращал любое значение tempdir независимо от типа, лишь бы оно не было None.

tempfile.gettempdirb()¶

То же, что и gettempdir(), но возвращаемое значение в байтах.

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

tempfile.gettempprefix()¶

Возвращает префикс имени файла, используемый для создания временных файлов. Не содержит компонент каталога.

tempfile.gettempprefixb()¶

То же, что и gettempprefix(), но возвращаемое значение в байтах.

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

Модуль использует глобальную переменную для хранения имени каталога, используемого для временных файлов, возвращаемых gettempdir(). Она может быть задана напрямую, чтобы переопределить процесс выбора, но это не рекомендуется. Все функции в этом модуле принимают аргумент dir, который может быть использован для указания каталога. Это рекомендуемый подход, который позволяет не удивлять ничего не подозревающий код изменением глобального поведения API.

tempfile.tempdir¶

При установке в значение, отличное от None, эта переменная определяет значение по умолчанию для аргумента dir функций, определенных в этом модуле, включая его тип, bytes или str. Она не может быть значением path-like object.

Если tempdir имеет значение None (по умолчанию) при любом вызове любой из вышеперечисленных функций, кроме gettempprefix(), она инициализируется по алгоритму, описанному в gettempdir().

Примечание

Имейте в виду, что если вы установите tempdir в значение байта, то возникнет неприятный побочный эффект: Глобальный возвращаемый тип по умолчанию mkstemp() и mkdtemp() изменяется на bytes, если нет явных аргументов prefix, suffix или dir типа str. Пожалуйста, не пишите код, ожидающий или зависящий от этого. Это неудобное поведение сохраняется для совместимости с исторической реализацией.

>>> import tempfile

# create a temporary file and write some data to it
>>> fp = tempfile.TemporaryFile()
>>> fp.write(b'Hello world!')
# read data from file
>>> fp.seek(0)
>>> fp.read()
b'Hello world!'
# close the file, it will be removed
>>> fp.close()

# create a temporary file using a context manager
>>> with tempfile.TemporaryFile() as fp:
...     fp.write(b'Hello world!')
...     fp.seek(0)
...     fp.read()
b'Hello world!'
>>>
# file is now closed and removed

# create a temporary directory using the context manager
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# directory and contents have been removed