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

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

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

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

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

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

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

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

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

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

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

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

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

tempfile.NamedTemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True): Эта функция работает точно так же, как TemporaryFile(), за исключением того, что файлу гарантируется видимое имя в файловой системе (в Unix запись в каталоге не удаляется). Это имя можно получить из атрибута name возвращаемого объекта, подобного файлу. Возможность повторного открытия файла по имени, пока временный файл с именем открыт, зависит от платформы (в Unix это возможно, в Windows NT и более поздних версиях — нет). Если delete равно True (по умолчанию), файл удаляется сразу после закрытия. Возвращаемый объект всегда является объектом, подобным файлу, у которого атрибут file является базовым объектом файла. Этот объект, подобный файлу, может использоваться в инструкции with, как и обычный файл.

tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=None, encoding=None, newline=None, suffix=None, prefix=None, dir=None)

Эта функция работает точно так же, как TemporaryFile(), за исключением того, что данные накапливаются в памяти до тех пор, пока размер файла не превысит max_size или пока не будет вызван метод fileno() файла, в этот момент содержимое записывается на диск, и работа продолжается, как с TemporaryFile().

Полученный файл имеет один дополнительный метод, rollover(), который заставляет файл перейти на файл на диске независимо от его размера.

Возвращаемый объект — это объект, подобный файлу, у которого атрибут _file является либо объектом io.BytesIO, либо io.StringIO (в зависимости от того, был ли указан двоичный или текстовый mode) или истинным объектом файла в зависимости от того, был ли вызван rollover(). Этот объект, подобный файлу, может использоваться в инструкции with, как и обычный файл.

Изменено в версии 3.3: метод truncate теперь принимает аргумент size.

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

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

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

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

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

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 указано, это указывает, следует ли открывать файл в бинарном режиме (по умолчанию) или текстовом. На некоторых платформах это не имеет значения.

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

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

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

Создаёт временную директорию максимально безопасным способом. Не возникает гонок при создании директории. Директория доступна только для чтения, записи и поиска пользователем, создавшим директорию.

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

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

mkdtemp() возвращает абсолютный путь к новой директории.

tempfile.gettempdir()

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

Python ищет в стандартном списке директорий ту, в которой вызывающий пользователь может создавать файлы. Список:

Директория, указанная в переменной окружения TMPDIR.
Директория, указанная в переменной окружения TEMP.
Директория, указанная в переменной окружения TMP.
Платформозависимое расположение:
- В Windows — директории C:\TEMP, C:\TMP, \TEMP, и \TMP, в указанном порядке.
- На всех остальных платформах — директории /tmp, /var/tmp, и /usr/tmp, в указанном порядке.
В качестве последней попытки — текущая рабочая директория.

Результат этого поиска кэшируется, см. описание tempdir ниже.

tempfile.gettempdirb(): То же, что gettempdir(), но возвращаемое значение в виде байтов.

Новое в версии 3.5.

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

tempfile.gettempprefixb(): То же, что gettempprefix(), но возвращаемое значение в виде байтов.

Новое в версии 3.5.

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

tempfile.tempdir

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

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

1. Примеры

Вот несколько примеров типичного использования модуля 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 directory using the context manager
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     print('created temporary directory', tmpdirname)
>>>
# directory and contents have been removed

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

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