tempfile — Generate temporary files and directories

Вихідний код: 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)

This function operates exactly as TemporaryFile() does, except that the file is guaranteed to have a visible name in the file system (on Unix, the directory entry is not unlinked). That name can be retrieved from the name attribute of the returned file-like object. Whether the name can be used to open the file a second time, while the named temporary file is still open, varies across platforms (it can be so used on Unix; it cannot on Windows). If delete is true (the default), the file is deleted as soon as it is closed. 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.

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

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

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

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)

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

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

Нове в версії 3.2.

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

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() returns the absolute pathname of the new directory if dir is None or is an absolute path. If dir is a relative path, mkdtemp() returns a relative path on Python 3.11 and lower. However, on 3.12 it will return an absolute path in all situations.

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

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

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

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

Нове в версії 3.5.

tempfile.gettempprefix()

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

tempfile.gettempprefixb()

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

Нове в версії 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 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