tempfile – Создание временных файлов и каталогов¶tempfile – Generate temporary files and directories

Исходный код: 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, как обычный файл.

Только в POSIX процесс, который был внезапно завершён с помощью SIGKILL, не может автоматически удалить созданные им NamedTemporaryFiles.

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

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

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

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

rollover()¶

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

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

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

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

Изменено в версии 3.11: Полностью реализует абстрактные базовые классы io.BufferedIOBase и io.TextIOBase (в зависимости от того, был ли указан бинарный или текстовый режим).

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

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

name¶

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

cleanup()¶

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

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

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

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

Вызывает событие аудита 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() возвращает абсолютный путь к новому каталогу, если dir равно None или является абсолютным путём. Если dir – относительный путь, mkdtemp() возвращает относительный путь в Python 3.11 и ниже. Однако начиная с версии 3.12 во всех случаях будет возвращаться абсолютный путь.

Вызывает событие аудита 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: Теперь всегда возвращает str. Ранее возвращал любое значение 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 значение типа bytes, возникает неприятный побочный эффект: глобальный возвращаемый тип по умолчанию для 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