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