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, 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(), за исключением того, что данные буферизуются в памяти до тех пор, пока размер файла не превысит max_size или пока не будет вызван метод fileno() файла, в этот момент содержимое записывается на диск, и работа продолжается как с TemporaryFile().

rollover()

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

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

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

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

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

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

Изменено в версии 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. Она не может быть объектом пути.

Если 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()
... # the file is closed, but not removed
... # open the file again by using its name
...     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