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

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

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

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

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

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

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

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

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

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 функций, определенных в этом модуле, включая его тип, байты или 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