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)

Эта функция работает точно так же, как TemporaryFile(), за исключением того, что файлу гарантируется видимое имя в файловой системе (в Unix запись не открепляется). Это имя можно получить из атрибута name возвращаемого объекта-подобного файлу. Возможность повторного открытия файла по имени, пока временный файл с именем все еще открыт, зависит от платформы (в Unix это возможно, в Windows — нет). Если delete истинно (по умолчанию), файл удаляется сразу после закрытия. Возвращаемый объект всегда представляет собой объект, подобный файлу, у которого атрибут 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(), за исключением того, что данные буферизуются в памяти до тех пор, пока размер файла не превысит 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)

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

name

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

cleanup()

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

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

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

Изменено в версии 3.6: Параметр 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: Возвращает всегда строку. Ранее возвращалось любое значение tempdir, независимо от типа, до тех пор, пока оно не было None.

tempfile.gettempdirb()

То же, что и gettempdir(), но возвращаемое значение — в виде байтов.

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

tempfile.gettempprefix()

Возвращает префикс имени файла, используемый для создания временных файлов. Он не включает компонент директории.

tempfile.gettempprefixb()

То же, что и gettempprefix(), но возвращаемое значение — в виде байтов.

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

Модуль использует глобальную переменную для хранения имени директории, используемой для временных файлов, возвращаемой gettempdir(). Её можно установить напрямую, чтобы переопределить процесс выбора, но это не рекомендуется. Все функции в этом модуле принимают аргумент dir, который можно использовать для указания директории. Это рекомендуемый подход, который не удивляет другой код, случайно изменяя глобальное поведение API.

tempfile.tempdir

Если установлено значение, отличное от None, эта переменная определяет значение по умолчанию для аргумента dir функций, определённых в этом модуле, включая его тип (байты или строка). Она не может быть объектом пути.

Если tempdir установлено в None (значение по умолчанию) при любом вызове любой из вышеуказанных функций, кроме gettempprefix(), она инициализируется в соответствии с алгоритмом, описанным в gettempdir().

Примечание

Обратите внимание, что если вы устанавливаете tempdir в значение типа байт, это приводит к нежелательному побочному эффекту: глобальный тип возвращаемого значения по умолчанию для mkstemp() и mkdtemp() изменяется на байты, когда явных аргументов suffix, prefix или dir типа строка не передано. Пожалуйста, не пишите код, ожидающий или зависящий от этого. Это неудобное поведение сохраняется для совместимости со старыми реализациями.

>>> 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