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.TextIOWrapper (в зависимости от того, был ли указан двоичный или текстовый режим 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 для использования соответствующего значения по умолчанию.

Изменено в версии 3.6: Параметр dir теперь принимает объект, подобный пути.

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

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

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

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

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

Изменено в версии 3.6: Параметр dir теперь принимает объект, подобный пути.

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().

Примеры

Вот некоторые примеры типичного использования модуля 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

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

Исторически временные файлы создавались путём сначала генерации имени файла с помощью функции 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