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, не может автоматически удалить созданные им именованные временные файлы.

Вызывает событие аудита 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() должен закрыть файловый дескриптор (например, с помощью os.close()) и удалить временный файл (например, с помощью os.remove()).

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

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

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

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

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

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)

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

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

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

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

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

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

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

Изменено в версии 3.12: теперь mkdtemp() всегда возвращает абсолютный путь, даже если dir является относительным.

tempfile.gettempdir()

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

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

1. Каталог, указанный переменной окружения TMPDIR.
2. Каталог, указанный переменной окружения TEMP.
3. Каталог, указанный переменной окружения TMP.

4. Расположение, зависящее от платформы:

   • В Windows каталоги %USERPROFILE%\AppData\Local\Temp, %SYSTEMROOT%\Temp, 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 функций этого модуля, включая его тип: 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