tempfile — Генерация временных файлов и каталогов

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

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

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

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

tempfile.TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)

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

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

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

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

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

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

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

tempfile.NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True): Эта функция работает точно так же, как TemporaryFile(), за исключением того, что файлу гарантированно присваивается видимое имя в файловой системе (в Unix запись каталога не удаляется). Это имя можно получить из атрибута name возвращаемого объекта, похожего на файл. Возможность повторного открытия файла по имени, в то время как именованный временный файл все еще открыт, зависит от платформы (это возможно в Unix; это невозможно в Windows NT или более поздних версиях). Если delete равно True (по умолчанию), файл удаляется сразу после закрытия. Возвращаемый объект всегда является объектом, похожим на файл, чье свойство file — это базовый истинный объект файла. Этот объект, похожий на файл, может быть использован в операторе with, как и обычный файл.

tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)

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

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

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

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

tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None)

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

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

Каталог можно явно очистить, вызвав метод cleanup().

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

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, они должны иметь одинаковый тип. Если они являются байтами, возвращаемое имя будет байтами, а не строкой. Если вы хотите принудительно получить возвращаемое значение в байтах при использовании значений по умолчанию, передайте suffix=b''.

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

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

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

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

Создаёт временную директорию максимально безопасным способом. В создании директории нет проблем с одновременным доступом. Директория доступна только для чтения, записи и поиска текущему пользователю.

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

Аргументы prefix, suffix и dir аналогичны аргументам функции mkstemp().

mkdtemp() возвращает абсолютный путь к новой директории.

tempfile.gettempdir()

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

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

Директория, указанная в переменной окружения TMPDIR.
Директория, указанная в переменной окружения TEMP.
Директория, указанная в переменной окружения TMP.
Платформенно-зависимое расположение:
- В Windows — каталоги C:\TEMP, C:\TMP, \TEMP, и \TMP, в указанном порядке.
- На всех других платформах — каталоги /tmp, /var/tmp, и /usr/tmp, в указанном порядке.
В качестве последнего средства — текущая рабочая директория.

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

tempfile.gettempdirb(): Аналогично gettempdir(), но возвращаемое значение — в байтах.

Новая функция в версии 3.5.

tempfile.gettempprefix(): Возвращает префикс имени файла, используемый для создания временных файлов. Он не включает компоненту каталога.

tempfile.gettempprefixb(): Аналогично gettempprefix(), но возвращаемое значение — в байтах.

Новая функция в версии 3.5.

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

tempfile.tempdir

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

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

11.6.1. Примеры

Ниже приведены примеры типичного использования модуля tempfile:

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

11.6.2. Устаревшие функции и переменные

Исторически существовал способ создания временных файлов, заключавшийся в предварительном получении имени файла с помощью функции mktemp() и последующем создании файла с этим именем. К сожалению, это не безопасно, так как другой процесс может создать файл с таким же именем между вызовом функции mktemp() и последующей попыткой создания файла первым процессом. Решением является одновременное выполнение обеих операций — немедленное создание файла. Этот подход используется функцией mkstemp() и другими описанными выше функциями.

tempfile.mktemp(suffix='', prefix='tmp', dir=None)

Устарело начиная с версии 2.3: Используйте mkstemp() вместо этого.

Возвращает абсолютный путь к файлу, которого не существовало во время вызова. Аргументы prefix, suffix и dir аналогичны аргументам функции mkstemp(), за исключением того, что имена файлов в байтах, suffix=None и prefix=None не поддерживаются.

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

Использование этой функции может создать уязвимость в вашей программе. К моменту, когда вы что-то делаете с возвращённым именем файла, кто-то другой может успеть его использовать. Использование mktemp() можно легко заменить на NamedTemporaryFile(), передав ему параметр delete=False:

>>> f = NamedTemporaryFile(delete=False)
>>> f.name
'/tmp/tmptjujjt'
>>> f.write(b"Hello World!\n")
13
>>> f.close()
>>> os.unlink(f.name)
>>> os.path.exists(f.name)
False