tempfile — Створення тимчасових файлів і каталогів

Вихідний код: Lib/tempfile.py

This module creates temporary files and directories. It works on all supported platforms. TemporaryFile, NamedTemporaryFile, TemporaryDirectory, and SpooledTemporaryFile are high-level interfaces which provide automatic cleanup and can be used as context managers. mkstemp() and mkdtemp() are lower-level functions which require manual cleanup.

Усі функції та конструктори, що викликаються користувачем, приймають додаткові аргументи, які дозволяють безпосередньо контролювати розташування та назву тимчасових файлів і каталогів. Імена файлів, які використовує цей модуль, включають рядок випадкових символів, що дозволяє безпечно створювати ці файли в спільних тимчасових каталогах. Щоб зберегти зворотну сумісність, порядок аргументів дещо дивний; для ясності рекомендується використовувати ключові аргументи.

Модуль визначає наступні елементи, викликані користувачем:

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

Повертає file-like object, який можна використовувати як тимчасову область зберігання. Файл створюється безпечно за тими ж правилами, що й mkstemp(). Його буде знищено, як тільки його закриють (включно з неявним закриттям, коли об’єкт збирають сміття). В Unix запис каталогу для файлу або не створюється взагалі, або видаляється одразу після створення файлу. Інші платформи не підтримують це; ваш код не повинен покладатися на тимчасовий файл, створений за допомогою цієї функції, який має або не має видимого імені у файловій системі.

The resulting object can be used as a context manager (see Приклади). On completion of the context or destruction of the file object the temporary file will be removed from the filesystem.

Параметр mode за умовчанням має значення 'w+b', щоб створений файл можна було читати та записувати без закриття. Двійковий режим використовується для того, щоб він працював узгоджено на всіх платформах, незалежно від даних, які зберігаються. буферизація, кодування, помилки та новий рядок інтерпретуються як для open().

Параметри dir, prefix і suffix мають те саме значення та значення за замовчуванням, що й mkstemp().

Повернений об’єкт є справжнім файловим об’єктом на платформах POSIX. На інших платформах це файлоподібний об’єкт, чий атрибут file є справжнім файловим об’єктом.

The os.O_TMPFILE flag is used if it is available and works (Linux-specific, requires Linux kernel 3.11 or later).

На платформах, які не є ні Posix, ні Cygwin, TemporaryFile є псевдонімом для NamedTemporaryFile.

Викликає подію перевірки tempfile.mkstemp з аргументом fullpath.

Змінено в версії 3.5: The os.O_TMPFILE flag is now used if available.

Змінено в версії 3.8: Додано параметр помилки.

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)

This function operates exactly as TemporaryFile() does, except the following differences:

  • This function returns a file that is guaranteed to have a visible name in the file system.

  • To manage the named file, it extends the parameters of TemporaryFile() with delete and delete_on_close parameters that determine whether and how the named file should be automatically deleted.

The returned object is always a file-like object whose file attribute is the underlying true file object. This file-like object can be used in a with statement, just like a normal file. The name of the temporary file can be retrieved from the name attribute of the returned file-like object. On Unix, unlike with the TemporaryFile(), the directory entry does not get unlinked immediately after the file creation.

If delete is true (the default) and delete_on_close is true (the default), the file is deleted as soon as it is closed. If delete is true and delete_on_close is false, the file is deleted on context manager exit only, or else when the file-like object is finalized. Deletion is not always guaranteed in this case (see object.__del__()). If delete is false, the value of delete_on_close is ignored.

Therefore to use the name of the temporary file to reopen the file after closing it, either make sure not to delete the file upon closure (set the delete parameter to be false) or, in case the temporary file is created in a with statement, set the delete_on_close parameter to be false. The latter approach is recommended as it provides assistance in automatic cleaning of the temporary file upon the context manager exit.

Opening the temporary file again by its name while it is still open works as follows:

  • On POSIX the file can always be opened again.

  • On Windows, make sure that at least one of the following conditions are fulfilled:

    • delete is false

    • additional open shares delete access (e.g. by calling os.open() with the flag O_TEMPORARY)

    • delete is true but delete_on_close is false. Note, that in this case the additional opens that do not share delete access (e.g. created via builtin open()) must be closed before exiting the context manager, else the os.unlink() call on context manager exit will fail with a PermissionError.

On Windows, if delete_on_close is false, and the file is created in a directory for which the user lacks delete access, then the os.unlink() call on exit of the context manager will fail with a PermissionError. This cannot happen when delete_on_close is true because delete access is requested by the open, which fails immediately if the requested access is not granted.

On POSIX (only), a process that is terminated abruptly with SIGKILL cannot automatically delete any NamedTemporaryFiles it created.

Викликає подію перевірки tempfile.mkstemp з аргументом fullpath.

Змінено в версії 3.8: Додано параметр помилки.

Змінено в версії 3.12: Added delete_on_close parameter.

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

This class operates exactly as TemporaryFile() does, except that data is spooled in memory until the file size exceeds max_size, or until the file’s fileno() method is called, at which point the contents are written to disk and operation proceeds as with TemporaryFile().

rollover()

The resulting file has one additional method, rollover(), which causes the file to roll over to an on-disk file regardless of its size.

The returned object is a file-like object whose _file attribute is either an io.BytesIO or io.TextIOWrapper object (depending on whether binary or text mode was specified) or a true file object, depending on whether rollover() has been called. This file-like object can be used in a with statement, just like a normal file.

Змінено в версії 3.3: the truncate method now accepts a size argument.

Змінено в версії 3.8: Додано параметр помилки.

Змінено в версії 3.11: Fully implements the io.BufferedIOBase and io.TextIOBase abstract base classes (depending on whether binary or text mode was specified).

class tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False, *, delete=True)

This class securely creates a temporary directory using the same rules as mkdtemp(). The resulting object can be used as a context manager (see Приклади). On completion of the context or destruction of the temporary directory object, the newly created temporary directory and all its contents are removed from the filesystem.

name

The directory name can be retrieved from the name attribute of the returned object. When the returned object is used as a context manager, the name will be assigned to the target of the as clause in the with statement, if there is one.

cleanup()

The directory can be explicitly cleaned up by calling the cleanup() method. If ignore_cleanup_errors is true, any unhandled exceptions during explicit or implicit cleanup (such as a PermissionError removing open files on Windows) will be ignored, and the remaining removable items deleted on a «best-effort» basis. Otherwise, errors will be raised in whatever context cleanup occurs (the cleanup() call, exiting the context manager, when the object is garbage-collected or during interpreter shutdown).

The delete parameter can be used to disable cleanup of the directory tree upon exiting the context. While it may seem unusual for a context manager to disable the action taken when exiting the context, it can be useful during debugging or when you need your cleanup behavior to be conditional based on other logic.

Викликає подію аудиту tempfile.mkdtemp з аргументом fullpath.

Added in version 3.2.

Змінено в версії 3.10: Додано параметр ignore_cleanup_errors.

Змінено в версії 3.12: Added the delete parameter.

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

Створює тимчасовий файл у максимально безпечний спосіб. Під час створення файлу немає умов змагання, припускаючи, що платформа правильно реалізує прапор os.O_EXCL для os.open(). Файл доступний для читання та запису лише ідентифікатором користувача, який його створив. Якщо платформа використовує біти дозволу, щоб вказати, чи є файл виконуваним, цей файл ніким не виконуваний. Файловий дескриптор не успадковується дочірніми процесами.

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

Якщо суфікс не None, назва файлу закінчуватиметься цим суфіксом, інакше суфікса не буде. mkstemp() не ставить крапку між назвою файлу та суфіксом; якщо він вам потрібен, поставте його на початку суфікса.

Якщо префікс не є None, ім’я файлу починатиметься з цього префікса; інакше використовується префікс за умовчанням. За замовчуванням повертається значення gettempprefix() або gettempprefixb(), відповідно.

Якщо dir не None, файл буде створено в цьому каталозі; інакше використовується каталог за замовчуванням. Каталог за замовчуванням вибирається зі списку, що залежить від платформи, але користувач програми може керувати розташуванням каталогу, установивши змінні середовища TMPDIR, TEMP або TMP. Таким чином, немає жодної гарантії, що згенероване ім’я файлу матиме якісь приємні властивості, наприклад, не вимагатиме цитування під час передачі зовнішнім командам через os.popen().

Якщо будь-які з суфікса, префікса та dir не є None, вони мають бути одного типу. Якщо це байти, повернена назва буде байтами замість str. Якщо ви хочете примусово повернути значення байтів із поведінкою за замовчуванням, передайте suffix=b''.

Якщо вказано текст і встановлено значення true, файл відкривається в текстовому режимі. В іншому випадку (за замовчуванням) файл відкривається у двійковому режимі.

mkstemp() повертає кортеж, що містить дескриптор рівня ОС до відкритого файлу (як би повернув os.open()) і абсолютний шлях до цього файлу в такому порядку.

Викликає подію перевірки tempfile.mkstemp з аргументом fullpath.

Змінено в версії 3.5: suffix, prefix і dir тепер можна вказувати в байтах, щоб отримати значення, що повертається. До цього дозволявся лише str. Суфікс і префікс тепер приймаються та за замовчуванням None, щоб використовувати відповідне значення за замовчуванням.

Змінено в версії 3.6: Параметр dir тепер приймає path-like object.

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

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

Користувач mkdtemp() несе відповідальність за видалення тимчасового каталогу та його вмісту після завершення роботи з ним.

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

mkdtemp() повертає абсолютний шлях до нового каталогу.

Викликає подію аудиту tempfile.mkdtemp з аргументом fullpath.

Змінено в версії 3.5: suffix, prefix і dir тепер можна вказувати в байтах, щоб отримати значення, що повертається. До цього дозволявся лише str. Суфікс і префікс тепер приймаються та за замовчуванням None, щоб використовувати відповідне значення за замовчуванням.

Змінено в версії 3.6: Параметр dir тепер приймає path-like object.

Змінено в версії 3.12: mkdtemp() now always returns an absolute path, even if dir is relative.

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(), але повертається значення в байтах.

Added in version 3.5.

tempfile.gettempprefix()

Повертає префікс імені файлу, який використовується для створення тимчасових файлів. Це не містить компонент каталогу.

tempfile.gettempprefixb()

Те саме, що gettempprefix(), але повертається значення в байтах.

Added in version 3.5.

Модуль використовує глобальну змінну для зберігання назви каталогу, що використовується для тимчасових файлів, які повертає gettempdir(). Його можна налаштувати безпосередньо для перевизначення процесу вибору, але це не рекомендується. Усі функції в цьому модулі приймають аргумент dir, який можна використовувати для визначення каталогу. Це рекомендований підхід, який не дивує інший нічого не підозрюючий код, змінюючи глобальну поведінку API.

tempfile.tempdir

Якщо встановлено значення, відмінне від None, ця змінна визначає значення за замовчуванням для аргументу dir для функцій, визначених у цьому модулі, включаючи його тип, bytes або str. Це не може бути path-like object.

Якщо tempdir має значення None (за замовчуванням) під час будь-якого виклику будь-якої з наведених вище функцій, крім gettempprefix(), вона ініціалізується відповідно до алгоритму, описаного в gettempdir().

Примітка

Пам’ятайте, що якщо ви встановите tempdir у значення байтів, виникне неприємний побічний ефект: глобальний тип повернення за замовчуванням mkstemp() і mkdtemp() змінюється на байти, якщо немає явного префікса ``, ``suffix або dir аргументи типу str. Будь ласка, не пишіть код, очікуючи або залежно від цього. Ця незручна поведінка зберігається для сумісності з історичною реалізацією.

Приклади

Ось декілька прикладів типового використання модуля 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 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

Застарілі функції та змінні

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