Сообщить об ошибке.

Функция rmtree() модуля shutil в Python

Рекурсивно удаляет содержимое папки/каталога

Синтаксис:

import shutil

shutil.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)

Параметры:

  • path - каталог удаления,
  • ignore_errors - игнорирование ошибок во время удаления,
  • onerror=None - обработчик ошибок, возникающих в процессе удаления (будет удален в Python 3.14.),
  • onexc=None - обработчик ошибок, возникающих в процессе удаления (добавлено в Python 3.12),
  • dir_fd=None - необязательный дескриптор (добавлен в Python 3.11).

Возвращаемое значение:

  • None

Описание:

Функция rmtree() модуля shutil рекурсивно удаляет все дерево каталогов. Путь path должен указывать на каталог, но не символическую ссылку на каталог.

Если значение ignore_errors равно true, то ошибки, возникающие в результате неудачного удаления, будут проигнорированы; если значение false или опущено, такие ошибки обрабатываются путем вызова обработчика, указанного onexc или onerror, или, если оба опущены, то исключения передаются вызывающей стороне.

Если ignore_errors=True, то возникшие ошибки в результате неудачного удаления, будут игнорироваться. Если False или пропущено, такие ошибки обрабатываются путем вызова обработчика, указанного в аргументах onexc ИЛИ onerror, или, если оба опущены, исключения передаются вызывающей стороне.

Аргумент onerror устарел и будет удален в Python 3.14.

Если указан onerror, это должен быть вызываемый объект, который принимает три аргумента: function, path и excinfo.

Первый аргумент function (у вызываемого объекта) является функцией, которая вызвала исключение. Это зависит от платформы и реализации. Второй параметр, path будет именем пути, переданным функции. Третий параметр excinfo будет информацией об исключении, возвращаемой sys.exc_info(). Исключения, вызванные ошибкой, обнаруживаться не будут.

Изменено в Python 3.12: Добавлен необязательный ключевой аргумент onexc, который является обработчиком ошибок, подобным onerror, но который ожидает экземпляр исключения, а не тройной кортеж (typ, val, tb).

Если указан onexc, это должен быть вызываемый объект, который принимает экземпляр исключения - три аргумента: function, path и excinfo. Например:

import shutil

def handle_error(func, path, excinfo):
    print(f"Ошибка при вызове функции {func.__name__} для пути {path}: {excinfo")

# Пытаемся удалить директорию, но с обработкой ошибок
shutil.rmtree('temp_dir', onexc=handle_error)

Изменено в Python 3.11: Добавлен необязательный ключевой аргумент dir_fd.

Эта функция может поддерживать пути относительно дескрипторов каталогов dir_fd.

Примечание: На платформах, поддерживающих необходимые функции на основе файлового дескриптора fd, по умолчанию используется стойкая к атакам на символические ссылки функция shutil.rmtree(). На других платформах реализация shutil.rmtree() восприимчива к атаке по символическим ссылкам: при надлежащем времени и обстоятельствах злоумышленники могут манипулировать символическими ссылками в файловой системе, чтобы удалить файлы, к которым они не могут получить доступ. Приложения могут использовать атрибут функции rmtree.avoids_symlink_attacks, чтобы определить, какой случай применим.

Вызывает событие аудита shutil.rmtree с аргументами path, dir_fd.

Изменено в Python 3.13: shutil.rmtree() теперь игнорирует исключения FileNotFoundError для всех путей, кроме пути верхнего уровня. Исключения, отличные от OSError и подклассов OSError, теперь всегда передаются вызывающей стороне.

rmtree.avoids_symlink_attacks:

Атрибут функции rmtree.avoids_symlink_attacks указывает, предоставляет ли текущая платформа и реализация версию rmtree(), устойчивую к атакам по символическим ссылкам. В настоящее время это верно только для платформ, поддерживающих функции доступа к каталогам на основе файлового дескриптора fd.

>>> import shutil
>>> shutil.rmtree.avoids_symlink_attacks
# True

Примеры использования shutil.rmtree().

В этом примере показано, как удалить дерево каталогов в Windows, где для некоторых файлов установлен бит только для чтения. Он использует обратный вызов onerror, чтобы очистить бит readonly и повторить попытку удаления.

import os, stat
import shutil

# обработчик ошибок 
def remove_readonly(func, path, _):
    "Очищает бит `read only` и повторяет попытку удаления"
    os.chmod(path, stat.S_IWRITE)
    func(path)


# для Python версии < 3.13
shutil.rmtree(directory, onerror=remove_readonly)
# или для Python 3.12 и выше
shutil.rmtree(directory, onexc=remove_readonly)