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 или новее).

Возникает событие аудита 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 равно True (по умолчанию), файл удаляется сразу после закрытия. Возвращаемый объект всегда является объектом, подобным файлу, чьё свойство 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: Метод truncate теперь принимает аргумент 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(). Файл доступен только для чтения и записи пользователем, создавшим файл. Если платформа использует биты разрешений для указания возможности выполнения файла, то файл не может быть выполнен никем. Дескриптор файла не наследуется дочерними процессами.

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

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

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

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

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

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

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

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

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

Изменено в версии 3.6: Параметр каталог теперь принимает объект, подобный пути.

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

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

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

Аргументы префикс, суффикс и каталог такие же, как у mkstemp().

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

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

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

Изменено в версии 3.6: Параметр каталог теперь принимает объект, подобный пути.

tempfile.gettempdir()

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

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

tempfile.tempdir

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

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

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