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 равно true (по умолчанию), файл удаляется сразу после закрытия. Возвращаемый объект всегда является объектом, подобным файлу, чьё свойство file является базовым истинным объектом файла. Этот объект, подобный файлу, можно использовать в операторе with, как и обычный файл.

Вызывает событие аудита 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(), который заставляет файл переместиться на диск независимо от его размера.

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

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

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

class tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False)

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

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

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

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

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

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

Изменено в версии 3.5: suffix, prefix и dir теперь могут быть переданы в виде байтов для получения значения в байтах. Ранее допускалось только str. 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 теперь могут быть переданы в виде байтов для получения значения в байтах. Ранее допускалось только str. 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: Возвращает всегда 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 в значение в байтах, возникает неприятное побочное действие: глобальный тип возвращаемых значений по умолчанию для mkstemp() и mkdtemp() меняется на байты, когда не указаны явные аргументы 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 directory using the context manager
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# directory and contents have been removed