11.6. tempfile – Генерация временных файлов и каталогов¶tempfile – Generate temporary files and directories

Исходный код: Lib/tempfile.py

Этот модуль создаёт временные файлы и каталоги. Он работает на всех поддерживаемых платформах. TemporaryFile, NamedTemporaryFile, TemporaryDirectory и SpooledTemporaryFile – высокоуровневые интерфейсы, которые обеспечивают автоматическую очистку и могут использоваться как менеджеры контекста. mkstemp() и mkdtemp() – низкоуровневые функции, требующие ручной очистки.

Все вызываемые пользователем функции и конструкторы принимают дополнительные аргументы, позволяющие напрямую управлять расположением и именем временных файлов и каталогов. Имена файлов, используемые этим модулем, содержат строку случайных символов, что позволяет безопасно создавать эти файлы в общих временных каталогах. Для сохранения обратной совместимости порядок аргументов несколько необычен; для ясности рекомендуется использовать именованные аргументы.

Модуль определяет следующие вызываемые пользователем элементы:

tempfile.TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)¶

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

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

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

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

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

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

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

tempfile.NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True)¶

Эта функция работает точно так же, как TemporaryFile(), за исключением того, что файл гарантированно имеет видимое имя в файловой системе (в Unix запись в каталоге не удаляется). Это имя можно получить из атрибута name возвращаемого файлоподобного объекта. Возможность использовать это имя для повторного открытия файла, пока именованный временный файл ещё открыт, зависит от платформы (в Unix это возможно; в Windows NT и новее – нет). Если delete равен true (по умолчанию), файл удаляется сразу после закрытия. Возвращаемый объект всегда является файлоподобным объектом, чей file атрибут является базовым настоящим файловым объектом. Этот файлоподобный объект можно использовать в операторе with, как обычный файл.

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

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

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

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

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

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

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

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

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

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

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

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

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

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)¶

Создаёт временный каталог максимально безопасным способом. В создании каталога нет состояний гонки. Каталог доступен для чтения, записи и поиска только создавшему его пользователю.

Пользователь mkdtemp() отвечает за удаление временного каталога и его содержимого после использования.

Аргументы prefix, suffix и dir такие же, как для mkstemp().

mkdtemp() возвращает абсолютный путь к новому каталогу.

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

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