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

Исходный код: Lib/tempfile.py

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

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

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

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, временный файл является псевдонимом для 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)¶

Эта функция работает точно так же, как и TemporaryFile(), за исключением того, что имя файла гарантированно будет отображаться в файловой системе (в Unix запись каталога не является несвязанной). Это имя может быть получено из атрибута name возвращаемого файлоподобного объекта. Можно ли использовать это имя для открытия файла во второй раз, пока именованный временный файл все еще открыт, зависит от платформы (это можно использовать в Unix, но нельзя в Windows). Если значение delete равно true (по умолчанию), файл удаляется сразу после его закрытия. Возвращаемый объект всегда является файлоподобным объектом, атрибут file которого является базовым истинным файловым объектом. Этот файлоподобный объект может использоваться в инструкции with, как и обычный файл.

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

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

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

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

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

name¶

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

cleanup()¶

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

Создает auditing event 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() несет ответственность за удаление временного файла, когда закончит с ним.

Если суффикс не равен None, имя файла будет заканчиваться этим суффиксом, в противном случае суффикса не будет. mkstemp() не ставит точку между именем файла и суффиксом; если он вам нужен, поставьте его в начале suffix.

Если префикс * не равен None, имя файла будет начинаться с этого префикса; в противном случае используется префикс по умолчанию. По умолчанию возвращается значение gettempprefix() или gettempprefixb(), в зависимости от обстоятельств.

Если значение dir не равно None, файл будет создан в этом каталоге; в противном случае используется каталог по умолчанию. Каталог по умолчанию выбирается из списка, зависящего от платформы, но пользователь приложения может управлять расположением каталога, установив переменные среды TMPDIR, TEMP или TMP. Таким образом, нет никакой гарантии, что сгенерированное имя файла будет обладать какими-либо приятными свойствами, например, не требовать кавычек при передаче внешним командам через os.popen().

Если какой-либо из suffix, prefix и dir не является None, они должны быть одного типа. Если они являются bytes, возвращаемое имя будет bytes вместо str. Если вы хотите принудительно вернуть значение в байтах с другим поведением по умолчанию, передайте suffix=b''.

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

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

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

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

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

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

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

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

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

mkdtemp() возвращает абсолютный путь к новому каталогу, если dir равен None или является абсолютным путем. Если dir является относительным путем, mkdtemp() возвращает относительный путь в Python 3.11 и более поздних версиях. Однако в версии 3.12 он будет возвращать абсолютный путь во всех ситуациях.

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

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

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

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. Это не может быть path-like object.

Если 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