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

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

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

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

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

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

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

Только в POSIX: процесс, аварийно завершённый сигналом SIGKILL, не может автоматически удалить созданные им файлы NamedTemporaryFile.

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

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

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

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

Изменено в версии 3.5: Теперь suffix, prefix и dir можно задавать как bytes, чтобы получить возвращаемое значение типа bytes. До этого разрешался только тип 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 можно задавать как bytes, чтобы получить возвращаемое значение типа bytes. До этого разрешался только тип str. Теперь для 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(), но возвращаемое значение имеет тип bytes.

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

tempfile.gettempprefix()

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

tempfile.gettempprefixb()

То же, что и gettempprefix(), но возвращаемое значение имеет тип bytes.

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

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

tempfile.tempdir

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

Если при вызове любой из перечисленных выше функций, кроме gettempprefix(), tempdir имеет значение None (по умолчанию), переменная инициализируется в соответствии с алгоритмом, описанным в 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