tempfile — Создать временные файлы и каталоги

Источник: Lib/tempfile.py

---

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

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

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

tempfile.TemporaryFile(mode='w+b', buffering=-1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

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

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

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

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

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

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

На платформах, которые не являются ни Posix, ни Cygwin, TemporaryFile - это псевдоним для NamedTemporaryFile.

Поднимает auditing event tempfile.mkstemp с аргументом fullpath.

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

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

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

Если delete равно true (по умолчанию) и delete_on_close равно true (по умолчанию), файл будет удален сразу после закрытия. Если delete равно true и delete_on_close равно false, файл будет удален только при выходе из контекстного менеджера или при завершении работы file-like object. Удаление в этом случае не всегда гарантировано (см. object.__del__()). Если delete равно false, значение delete_on_close игнорируется.

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

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

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

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

  • удаление - это ложь

  • дополнительные открытые доли удаляют доступ (например, путем вызова os.open() с флагом O_TEMPORARY)

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

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

В POSIX (только) процесс, который завершается внезапно с помощью SIGKILL, не может автоматически удалить созданные им NamedTemporaryFiles.

Поднимает auditing event tempfile.mkstemp с аргументом fullpath.

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

Изменено в версии 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: Добавлен параметр ошибки.

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

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

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

name

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

cleanup()

Каталог можно явно очистить, вызвав метод cleanup(). Если ignore_cleanup_errors равно true, любые необработанные исключения во время явной или неявной очистки (например, вызов PermissionError для удаления открытых файлов в Windows) будут проигнорированы, а оставшиеся удаляемые элементы удалены по принципу «из лучших побуждений». В противном случае ошибки будут возникать при любой контекстной очистке (вызов cleanup(), выход из контекстного менеджера, сборка объекта из мусора или завершение работы интерпретатора).

Параметр delete можно использовать для отключения очистки дерева каталогов при выходе из контекста. Хотя может показаться необычным, что менеджер контекста отключает действие, выполняемое при выходе из контекста, это может быть полезно при отладке или когда вам нужно, чтобы поведение очистки было условным, основанным на другой логике.

Поднимает auditing event tempfile.mkdtemp с аргументом fullpath.

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

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

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

Поднимает auditing event tempfile.mkstemp с аргументом fullpath.

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

Изменено в версии 3.6: Параметр dir теперь принимает значение path-like object.

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

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

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

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

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

Поднимает auditing event tempfile.mkdtemp с аргументом fullpath.

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

Изменено в версии 3.6: Параметр dir теперь принимает значение path-like object.

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

tempfile.gettempdirb()

Аналогично gettempdir(), но возвращаемое значение в байтах.

Added in version 3.5.

tempfile.gettempprefix()

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

tempfile.gettempprefixb()

Аналогично gettempprefix(), но возвращаемое значение в байтах.

Added in version 3.5.

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

tempfile.tempdir

При установке значения, отличного от None, эта переменная определяет значение по умолчанию для аргумента dir функций, определенных в этом модуле, включая его тип, bytes или str. Она не может быть значением path-like object.

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

Примечание

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

Примеры

Вот несколько примеров типичного использования модуля tempfile:

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

Утраченные функции и переменные

Исторический способ создания временных файлов заключался в том, чтобы сначала сгенерировать имя файла с помощью функции mktemp(), а затем создать файл с этим именем. К сожалению, это небезопасно, поскольку за время между вызовом mktemp() и последующей попыткой создания файла первым процессом другой процесс может создать файл с таким именем. Решение состоит в том, чтобы объединить эти два шага и создать файл сразу. Такой подход используется в mkstemp() и других функциях, описанных выше.

tempfile.mktemp(suffix='', prefix='tmp', dir=None)

Не рекомендуется, начиная с версии 2.3: Вместо этого используйте mkstemp().

Возвращает абсолютное имя пути к файлу, который не существовал на момент вызова. Аргументы prefix, suffix и dir аналогичны аргументам mkstemp(), за исключением того, что имена байтовых файлов, suffix=None и prefix=None не поддерживаются.

Предупреждение

Использование этой функции может создать брешь в безопасности вашей программы. К тому времени, когда вы начнете делать что-либо с именем файла, которое она возвращает, кто-то другой может опередить вас. Использование mktemp() можно легко заменить на NamedTemporaryFile(), передав ему параметр delete=False:

>>> f = NamedTemporaryFile(delete=False)
>>> f.name
'/tmp/tmptjujjt'
>>> f.write(b"Hello World!\n")
13
>>> f.close()
>>> os.unlink(f.name)
>>> os.path.exists(f.name)
False