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)

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

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

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

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

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

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

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

Вызывает событие аудита tempfile.mkstemp с аргументом fullpath.

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

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

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, как и обычный файл.

Вызывает событие аудита tempfile.mkstemp с аргументом fullpath.

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

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

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

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

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

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

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

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

Вызывает событие аудита tempfile.mkdtemp с аргументом fullpath.

Добавлена в версии 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()) и абсолютный путь к этому файлу в указанном порядке.

Вызывает событие аудита аудита tempfile.mkstemp с аргументом fullpath.

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

Вызывает событие аудита аудита tempfile.mkdtemp с аргументом fullpath.

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

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

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 ниже.

tempfile.gettempdirb()

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

Введено в версии 3.5.

tempfile.gettempprefix()

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

tempfile.gettempprefixb()

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

Введено в версии 3.5.

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

tempfile.tempdir

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

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

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