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, delete_on_close=True)¶

Эта функция работает точно так же, как TemporaryFile(), за следующими исключениями:

• Эта функция возвращает файл, который гарантированно имеет видимое имя в файловой системе.

• Для управления именованным файлом она расширяет параметры TemporaryFile() параметрами delete и delete_on_close, которые определяют, должен ли именованный файл автоматически удаляться и как именно.

Возвращаемый объект всегда является файлоподобным объектом, чей атрибут file является базовым настоящим файловым объектом. Этот файлоподобный объект можно использовать в операторе with, как обычный файл. Имя временного файла можно получить из атрибута name возвращаемого файлоподобного объекта. В Unix, в отличие от TemporaryFile(), запись каталога не удаляется сразу после создания файла.

Если delete равен true (по умолчанию) и delete_on_close равен true (по умолчанию), файл удаляется сразу после закрытия. Если delete равен true и delete_on_close равен false, файл удаляется только при выходе из менеджера контекста или при финализации файлоподобного объекта. Удаление не всегда гарантируется в этом случае (см. object.__del__()). Если delete равен false, значение delete_on_close игнорируется.

Поэтому, чтобы использовать имя временного файла для повторного открытия после закрытия, либо убедитесь, что файл не удаляется при закрытии (установите параметр delete в false), либо, если временный файл создаётся в операторе with, установите параметр delete_on_close в false. Рекомендуется второй подход, поскольку он обеспечивает автоматическую очистку временного файла при выходе из менеджера контекста.

Повторное открытие временного файла по его имени, пока он ещё открыт, работает следующим образом:

• В POSIX файл всегда можно открыть повторно.

• В Windows убедитесь, что выполняется хотя бы одно из следующих условий:

  • delete равен false

  • дополнительное открытие разделяет доступ на удаление (например, вызов os.open() с флагом O_TEMPORARY)

  • delete равен true, а delete_on_close равен false. Обратите внимание, что в этом случае дополнительные открытия, которые не разделяют доступ на удаление (например, созданные через встроенный open()), должны быть закрыты до выхода из менеджера контекста, иначе вызов os.unlink() при выходе из менеджера контекста завершится ошибкой PermissionError.

В Windows, если delete_on_close равен false, и файл создаётся в каталоге, для которого у пользователя нет прав на удаление, то вызов os.unlink() при выходе из менеджера контекста завершится ошибкой PermissionError. Этого не может произойти, когда delete_on_close равен true, потому что право на удаление запрашивается при открытии, и оно сразу завершится ошибкой, если запрошенное право не предоставлено.

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

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

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

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

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, *, delete=True)¶

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

name¶

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

cleanup()¶

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

Параметр delete можно использовать для отключения очистки дерева каталогов при выходе из контекста. Хотя может показаться необычным, что менеджер контекста отключает действие при выходе из контекста, это может быть полезно во время отладки или когда нужно, чтобы поведение очистки было условным в зависимости от другой логики.

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

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

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

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

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

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

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

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

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

Изменено в версии 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 file using a context manager
# close the file, use the name to open the file again
>>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
...     fp.write(b'Hello world!')
...     fp.close()
... # файл закрыт, но не удалён
... # открыть файл снова по его имени
...     with open(fp.name, mode='rb') as f:
...         f.read()
b'Hello world!'
>>>
# file is now 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