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

Данный модуль создаёт временные файлы и каталоги. Он работает на всех поддерживаемых платформах. 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 или выше).

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

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

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

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: Метод усечения теперь принимает аргумент size.

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

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

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

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

Каталог можно явно очистить, вызвав метод cleanup().

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

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

tempfile.mkstemp(suffix=None, prefix=None, dir=None, text=False)

Создаёт временный файл максимально безопасным способом. При создании файла отсутствуют условия гонки, если предположить, что платформа правильно реализует флаг os.O_EXCL для os.open(). Файл доступен для чтения и записи только создавшему ID пользователя. Если платформа использует биты разрешений для указания того, является ли файл исполняемым, то данный файл не может выполняться никем. Дескриптор файла не наследуется дочерними процессами.

В отличие от TemporaryFile(), пользователь mkstemp() несет ответственность за удаление временного файла по завершении работы с ним.

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

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

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

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

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

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)

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

Пользователь 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 ниже.

tempfile.gettempdirb()

То же, что и gettempdir(), но возвращаемое значение находится в байтах.

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

tempfile.gettempprefix()

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

tempfile.gettempprefixb()

То же, что и gettempprefix(), но возвращаемое значение находится в байтах.

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

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

tempfile.tempdir

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

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

Примеры

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

>>> import tempfile

# создадим временный файл и запишем в него некоторые данные
>>> fp = tempfile.TemporaryFile()
>>> fp.write(b'Hello world!')
# прочитаем данные из файла
>>> fp.seek(0)
>>> fp.read()
b'Hello world!'
# закроем файл, он будет удален
>>> fp.close()

# создадим временный файл, используя менеджер контекста
>>> with tempfile.TemporaryFile() as fp:
...     fp.write(b'Hello world!')
...     fp.seek(0)
...     fp.read()
b'Hello world!'
>>>
# файл закрыт и удален

# создадим временный каталог с помощью менеджера контекста
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('создал временный каталог', tmpdirname)
>>>
# каталог и содержимое были удалены

Устаревшие функции и переменные

Исторический способ создания временных файлов заключался в том, чтобы сначала сгенерировать имя файла с помощью функции 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