`shutil.md`

487 строк · 56.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.9/library/shutil.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`shutil`](https://python-all.ru/3.9/library/shutil.html#module-shutil) – высокоуровневые операции с файлами89**Исходный код:** [Lib/shutil.py](https://python-all.ru/src/3.9/Lib/shutil.py)1011---1213Модуль [`shutil`](https://python-all.ru/3.9/library/shutil.html#module-shutil) предоставляет ряд высокоуровневых операций с файлами и наборами файлов. В частности, предоставлены функции, которые поддерживают копирование и удаление файлов. Для операций с отдельными файлами см. также модуль [`os`](https://python-all.ru/3.9/library/os.html#module-os).1415> **Предупреждение**16>17> Даже функции копирования файлов высокого уровня ([`shutil.copy()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy), [`shutil.copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2)) не могут скопировать все метаданные файла.18>19> На платформах POSIX это означает, что владелец и группа файла теряются, а также ACL. На Mac OS не используются ресурсные форки и другие метаданные. Это означает, что ресурсы будут потеряны, а коды типа и создателя файла будут некорректными. В Windows владельцы файлов, ACL и альтернативные потоки данных не копируются.2021## Операции с каталогами и файлами2223#### `shutil.copyfileobj(fsrc, fdst[, length])`2425Копирует содержимое файлоподобного объекта *fsrc* в файлоподобный объект *fdst*. Целое число *length*, если задано, определяет размер буфера. В частности, отрицательное значение *length* означает копирование данных без разбиения исходных данных на части; по умолчанию данные читаются порциями, чтобы избежать неконтролируемого расхода памяти. Обратите внимание: если текущая позиция в файле объекта *fsrc* не равна 0, будут скопированы только данные от текущей позиции до конца файла.2627#### `shutil.copyfile(src, dst, *, follow_symlinks=True)`2829Копирует содержимое (без метаданных) файла с именем *src* в файл с именем *dst* и возвращает *dst* наиболее эффективным способом. *src* и *dst* являются путь-подобными объектами или именами путей, заданными в виде строк.3031*dst* должно быть полным именем целевого файла; см. [`copy()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy) для копирования, принимающего путь к целевому каталогу. Если *src* и *dst* указывают на один и тот же файл, возбуждается [`SameFileError`](https://python-all.ru/3.9/library/shutil.html#shutil.SameFileError).3233Целевое расположение должно быть доступно для записи; в противном случае будет возбуждено исключение [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError). Если *dst* уже существует, оно будет заменено. Специальные файлы, такие как символьные или блочные устройства и каналы, не могут быть скопированы с помощью этой функции.3435Если *follow\_symlinks* имеет значение false и *src* является символической ссылкой, будет создана новая символическая ссылка вместо копирования файла, на который указывает *src*.3637Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copyfile` с аргументами `src`, `dst`.3839Изменено в версии 3.3: [`IOError`](https://python-all.ru/3.9/library/exceptions.html#IOError) ранее возбуждалось вместо [`OSError`](https://python-all.ru/3.9/library/exceptions.html#OSError). Добавлен аргумент *follow\_symlinks*. Теперь возвращает *dst*.4041Изменено в версии 3.4: Возбуждается [`SameFileError`](https://python-all.ru/3.9/library/shutil.html#shutil.SameFileError) вместо [`Error`](https://python-all.ru/3.9/library/shutil.html#shutil.Error). Поскольку первое является подклассом второго, это изменение обратно совместимо.4243Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел [Платформенно-зависимые эффективные операции копирования](https://python-all.ru/3.9/library/shutil.html#shutil-platform-dependent-efficient-copy-operations).4445#### `exception shutil.SameFileError`4647Это исключение возбуждается, если источник и назначение в [`copyfile()`](https://python-all.ru/3.9/library/shutil.html#shutil.copyfile) являются одним и тем же файлом.4849Новое в версии 3.4.5051#### `shutil.copymode(src, dst, *, follow_symlinks=True)`5253Копирует биты прав доступа из *src* в *dst*. Содержимое файла, владелец и группа не изменяются. *src* и *dst* являются путь-подобными объектами или именами путей, заданными в виде строк. Если *follow\_symlinks* равен false и оба *src* и *dst* являются символическими ссылками, [`copymode()`](https://python-all.ru/3.9/library/shutil.html#shutil.copymode) попытается изменить режим самой *dst* (а не файла, на который она указывает). Эта функциональность доступна не на всех платформах; подробнее см. [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat). Если [`copymode()`](https://python-all.ru/3.9/library/shutil.html#shutil.copymode) не может изменить символические ссылки на данной платформе, а запрос на это поступил, вызов ничего не делает и возвращает управление.5455Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copymode` с аргументами `src`, `dst`.5657Изменено в версии 3.3: Добавлен аргумент *follow\_symlinks*.5859#### `shutil.copystat(src, dst, *, follow_symlinks=True)`6061Копирует биты прав доступа, время последнего доступа, время последнего изменения и флаги из *src* в *dst*. В Linux [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) также копирует «расширенные атрибуты» там, где это возможно. Содержимое файла, владелец и группа не изменяются. *src* и *dst* являются путь-подобными объектами или именами путей, заданными в виде строк.6263Если *follow\_symlinks* имеет значение false и *src* и *dst* оба ссылаются на символические ссылки, [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) будет работать с самими символическими ссылками, а не с файлами, на которые эти символические ссылки указывают – читая информацию из символической ссылки *src* и записывая информацию в символическую ссылку *dst*.6465> **Примечание**66>67> Не все платформы предоставляют возможность просматривать и изменять символические ссылки. Python сам может сообщить, какая функциональность доступна локально.68>69> - Если `os.chmod in os.supports_follow_symlinks` равен `True`, [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) может изменять биты разрешений символической ссылки.70> - Если `os.utime in os.supports_follow_symlinks` равен `True`, [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) может изменять время последнего доступа и изменения символической ссылки.71> - Если `os.chflags in os.supports_follow_symlinks` равно `True`, [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) может изменять флаги символической ссылки. (`os.chflags` доступен не на всех платформах.)72>73> На платформах, где часть или вся эта функциональность недоступна, при попытке изменить символическую ссылку [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) скопирует всё, что сможет. [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) никогда не возвращает ошибку.74>75> Подробнее см. [`os.supports_follow_symlinks`](https://python-all.ru/3.9/library/os.html#os.supports_follow_symlinks).7677Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copystat` с аргументами `src`, `dst`.7879Изменено в версии 3.3: Добавлен аргумент *follow\_symlinks* и поддержка расширенных атрибутов Linux.8081#### `shutil.copy(src, dst, *, follow_symlinks=True)`8283Копирует файл *src* в файл или каталог *dst*. *src* и *dst* должны быть [path-like objects](https://python-all.ru/3.9/glossary.html#term-path-like-object) или строками. Если *dst* указывает на каталог, файл будет скопирован в *dst* с использованием базового имени из *src*. Если *dst* указывает на уже существующий файл, он будет заменён. Возвращает путь к созданному файлу.8485Если *follow\_symlinks* имеет значение false и *src* является символической ссылкой, *dst* будет создан как символическая ссылка. Если *follow\_symlinks* имеет значение true и *src* является символической ссылкой, *dst* будет копией файла, на который указывает *src*.8687[`copy()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy) копирует данные файла и его режим доступа (см. [`os.chmod()`](https://python-all.ru/3.9/library/os.html#os.chmod)). Другие метаданные, такие как время создания и изменения файла, не сохраняются. Чтобы сохранить все метаданные исходного файла, используйте [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2).8889Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copyfile` с аргументами `src`, `dst`.9091Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copymode` с аргументами `src`, `dst`.9293Изменено в версии 3.3: Добавлен аргумент *follow\_symlinks*. Теперь возвращает путь к созданному файлу.9495Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел [Платформенно-зависимые эффективные операции копирования](https://python-all.ru/3.9/library/shutil.html#shutil-platform-dependent-efficient-copy-operations).9697#### `shutil.copy2(src, dst, *, follow_symlinks=True)`9899Идентично [`copy()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy), за исключением того, что [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2) также пытается сохранить метаданные файла.100101Когда *follow\_symlinks* равен false, а *src* – символическая ссылка, [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2) пытается скопировать все метаданные из символической ссылки *src* в только что созданную символическую ссылку *dst*. Однако эта возможность доступна не на всех платформах. На платформах, где часть или вся эта функциональность недоступна, [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2) сохранит все метаданные, которые сможет; [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2) никогда не вызывает исключение, если не удаётся сохранить метаданные файла.102103[`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2) использует [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat) для копирования метаданных файла. Подробнее о поддержке платформами изменения метаданных символических ссылок см. [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat).104105Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copyfile` с аргументами `src`, `dst`.106107Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copystat` с аргументами `src`, `dst`.108109Изменено в версии 3.3: Добавлен аргумент *follow\_symlinks*, также предпринята попытка копировать расширенные атрибуты файловой системы (пока только Linux). Теперь возвращает путь к созданному файлу.110111Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел [Платформенно-зависимые эффективные операции копирования](https://python-all.ru/3.9/library/shutil.html#shutil-platform-dependent-efficient-copy-operations).112113#### `shutil.ignore_patterns(*patterns)`114115Эта фабричная функция создаёт функцию, которую можно использовать как вызываемый объект для аргумента *ignore* функции [`copytree()`](https://python-all.ru/3.9/library/shutil.html#shutil.copytree), игнорируя файлы и каталоги, соответствующие одному из предоставленных *шаблонов* в стиле glob. См. пример ниже.116117#### `shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)`118119Рекурсивно копирует всё дерево каталогов с корнем в *src* в каталог с именем *dst* и возвращает целевой каталог. Все промежуточные каталоги, необходимые для размещения *dst*, также будут созданы по умолчанию.120121Права доступа и временные метки каталогов копируются с помощью [`copystat()`](https://python-all.ru/3.9/library/shutil.html#shutil.copystat), отдельные файлы копируются с помощью [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2).122123Если *symlinks* имеет значение true, символические ссылки в исходном дереве представляются как символические ссылки в новом дереве, и метаданные исходных ссылок будут скопированы насколько это позволяет платформа; если false или аргумент опущен, содержимое и метаданные файлов, на которые указывают ссылки, копируются в новое дерево.124125Когда *symlinks* равен false, если файл, на который указывает символическая ссылка, не\\ nсуществует, исключение будет добавлено в список ошибок, вызываемых в исключении [`Error`](https://python-all.ru/3.9/library/shutil.html#shutil.Error) в конце процесса копирования. Можно установить опциональный флаг *ignore\_dangling\_symlinks* в true, если требуется подавить это исключение. Обратите внимание, что эта опция не действует на платформах, не поддерживающих [`os.symlink()`](https://python-all.ru/3.9/library/os.html#os.symlink).126127Если задан *ignore*, это должен быть вызываемый объект, который будет получать в качестве аргументов каталог, обрабатываемый [`copytree()`](https://python-all.ru/3.9/library/shutil.html#shutil.copytree), и список его содержимого, возвращённый [`os.listdir()`](https://python-all.ru/3.9/library/os.html#os.listdir). Поскольку [`copytree()`](https://python-all.ru/3.9/library/shutil.html#shutil.copytree) вызывается рекурсивно, вызываемый объект *ignore* будет вызываться один раз для каждого копируемого каталога. Вызываемый объект должен возвращать последовательность имён каталогов и файлов относительно текущего каталога (т.е. подмножество элементов из его второго аргумента); эти имена будут игнорироваться в процессе копирования. [`ignore_patterns()`](https://python-all.ru/3.9/library/shutil.html#shutil.ignore_patterns) можно использовать для создания такого вызываемого объекта, который игнорирует имена на основе шаблонов в стиле glob.128129Если возникают исключения, вызывается [`Error`](https://python-all.ru/3.9/library/shutil.html#shutil.Error) со списком причин.130131Если задан *copy\_function*, это должен быть вызываемый объект, который будет использоваться для копирования каждого файла. Он будет вызван с исходным и целевым путями в качестве аргументов. По умолчанию используется [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2), но можно использовать любую функцию с той же сигнатурой (например, [`copy()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy)).132133Если *dirs\_exist\_ok* имеет значение false (по умолчанию) и *dst* уже существует, вызывается [`FileExistsError`](https://python-all.ru/3.9/library/exceptions.html#FileExistsError). Если *dirs\_exist\_ok* имеет значение true, операция копирования будет продолжена, если встретятся существующие каталоги, а файлы в дереве *dst* будут перезаписаны соответствующими файлами из дерева *src*.134135Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.copytree` с аргументами `src`, `dst`.136137Изменено в версии 3.3: Копирует метаданные, когда *symlinks* имеет значение false. Теперь возвращает *dst*.138139Изменено в версии 3.2: Добавлен аргумент *copy\_function* для возможности предоставления пользовательской функции копирования. Добавлен аргумент *ignore\_dangling\_symlinks* для подавления ошибок, связанных с висячими символическими ссылками, когда *symlinks* имеет значение false.140141Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел [Платформенно-зависимые эффективные операции копирования](https://python-all.ru/3.9/library/shutil.html#shutil-platform-dependent-efficient-copy-operations).142143Новое в версии 3.8: Параметр *dirs\_exist\_ok*.144145#### `shutil.rmtree(path, ignore_errors=False, onerror=None)`146147Удаляет целое дерево каталогов; *path* должен указывать на каталог (но не на символическую ссылку на каталог). Если *ignore\_errors* равен true, ошибки, возникающие при неудачном удалении, игнорируются; если false или не указан, такие ошибки обрабатываются вызовом обработчика, заданного *onerror*, или, если он не указан, вызывается исключение.148149> **Примечание**150>151> На платформах, поддерживающих необходимые функции на основе файловых дескрипторов, по умолчанию используется версия [`rmtree()`](https://python-all.ru/3.9/library/shutil.html#shutil.rmtree), устойчивая к атакам через символические ссылки. На других платформах реализация [`rmtree()`](https://python-all.ru/3.9/library/shutil.html#shutil.rmtree) уязвима для такой атаки: при правильном выборе времени и обстоятельств злоумышленники могут манипулировать символическими ссылками в файловой системе, чтобы удалить файлы, к которым иначе у них не было бы доступа. Приложения могут использовать атрибут функции [`rmtree.avoids_symlink_attacks`](https://python-all.ru/3.9/library/shutil.html#shutil.rmtree.avoids_symlink_attacks), чтобы определить применимый вариант.152153Если *onerror* задан, он должен быть вызываемым объектом, принимающим три параметра: *function*, *path* и *excinfo*.154155Первый параметр, *function*, – это функция, вызвавшая исключение; он зависит от платформы и реализации. Второй параметр, *path*, будет именем пути, переданным в *function*. Третий параметр, *excinfo*, будет информацией об исключении, возвращаемой [`sys.exc_info()`](https://python-all.ru/3.9/library/sys.html#sys.exc_info). Исключения, вызванные *onerror*, не перехватываются.156157Вызывает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.rmtree` с аргументом `path`.158159Изменено в версии 3.3: Добавлена версия, устойчивая к атакам через символические ссылки, которая используется автоматически, если платформа поддерживает функции на основе файловых дескрипторов.160161Изменено в версии 3.8: В Windows больше не удаляет содержимое точки соединения каталогов перед её удалением.162163#### `rmtree.avoids_symlink_attacks`164165Указывает, предоставляют ли текущая платформа и реализация версию [`rmtree()`](https://python-all.ru/3.9/library/shutil.html#shutil.rmtree), устойчивую к атакам через символические ссылки. В настоящее время это верно только для платформ, поддерживающих функции доступа к каталогам на основе файловых дескрипторов.166167Новое в версии 3.3.168169#### `shutil.move(src, dst, copy_function=copy2)`170171Рекурсивно перемещает файл или каталог (*src*) в другое место (*dst*) и возвращает путь назначения.172173Если назначение – существующий каталог, то *src* перемещается внутрь этого каталога. Если назначение уже существует, но не является каталогом, оно может быть перезаписано в зависимости от семантики [`os.rename()`](https://python-all.ru/3.9/library/os.html#os.rename).174175Если назначение находится в той же файловой системе, то используется [`os.rename()`](https://python-all.ru/3.9/library/os.html#os.rename). В противном случае *src* копируется в *dst* с помощью *copy\_function* и затем удаляется. В случае символических ссылок будет создана новая символическая ссылка, указывающая на цель *src*, в или как *dst*, а *src* будет удалён.176177Если *copy\_function* указан, он должен быть вызываемым объектом, принимающим два аргумента *src* и *dst*, и будет использоваться для копирования *src* в *dst*, если [`os.rename()`](https://python-all.ru/3.9/library/os.html#os.rename) не может быть использован. Если исходный объект – каталог, вызывается [`copytree()`](https://python-all.ru/3.9/library/shutil.html#shutil.copytree) с передачей ему `copy_function()`. По умолчанию *copy\_function* – [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2). Использование [`copy()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy) в качестве *copy\_function* позволяет выполнить перемещение, когда невозможно также скопировать метаданные, ценой отсутствия копирования любых метаданных.178179Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.move` с аргументами `src`, `dst`.180181Изменено в версии 3.3: Добавлена явная обработка символических ссылок для внешних файловых систем, что адаптирует поведение к GNU **mv**. Теперь возвращает *dst*.182183Изменено в версии 3.5: Добавлен именованный аргумент *copy\_function*.184185Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые системные вызовы быстрого копирования для более эффективного копирования файлов. См. раздел [Платформенно-зависимые эффективные операции копирования](https://python-all.ru/3.9/library/shutil.html#shutil-platform-dependent-efficient-copy-operations).186187Изменено в версии 3.9: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object) как для *src*, так и для *dst*.188189#### `shutil.disk_usage(path)`190191Возвращает статистику использования диска для указанного пути в виде [именованного кортежа](https://python-all.ru/3.9/glossary.html#term-named-tuple) с атрибутами *total*, *used* и *free*, которые представляют общий, используемый и свободный объём в байтах. *path* может быть файлом или каталогом.192193Новое в версии 3.3.194195Изменено в версии 3.8: В Windows *path* теперь может быть файлом или каталогом.196197[Доступность](https://python-all.ru/3.9/library/intro.html#availability): Unix, Windows.198199#### `shutil.chown(path, user=None, group=None)`200201Изменяет владельца *user* и/или группу *group* для указанного *path*.202203*user* может быть системным именем пользователя или uid; то же самое относится к *group*. Требуется хотя бы один аргумент.204205См. также [`os.chown()`](https://python-all.ru/3.9/library/os.html#os.chown) – базовую функцию.206207Вызывает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.chown` с аргументами `path`, `user`, `group`.208209[Доступность](https://python-all.ru/3.9/library/intro.html#availability): Unix.210211Новое в версии 3.3.212213#### `shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)`214215Возвращает путь к исполняемому файлу, который был бы запущен, если бы была вызвана заданная команда *cmd*. Если команда *cmd* не будет вызвана, возвращает `None`.216217*mode* – это маска разрешений, передаваемая в [`os.access()`](https://python-all.ru/3.9/library/os.html#os.access), по умолчанию определяющая, существует ли файл и является ли он исполняемым.218219Если *path* не указан, используются результаты [`os.environ()`](https://python-all.ru/3.9/library/os.html#os.environ), возвращающие либо значение «PATH», либо запасной вариант [`os.defpath`](https://python-all.ru/3.9/library/os.html#os.defpath).220221В Windows текущий каталог всегда добавляется в начало *path*, независимо от того, используется значение по умолчанию или указано своё; такое же поведение применяет командная оболочка при поиске исполняемых файлов. Кроме того, при поиске *cmd* в *path* проверяется переменная окружения `PATHEXT`. Например, при вызове `shutil.which("python")` функция [`which()`](https://python-all.ru/3.9/library/shutil.html#shutil.which) будет искать `PATHEXT`, чтобы узнать, что нужно искать `python.exe` в каталогах из *path*. Например, в Windows:222223```python224>>> shutil.which("python")225'C:\\Python33\\python.EXE'226```227228Новое в версии 3.3.229230Изменено в версии 3.8: Теперь принимается тип [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes). Если тип *cmd* – [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes), то тип результата также [`bytes`](https://python-all.ru/3.9/library/stdtypes.html#bytes).231232#### `exception shutil.Error`233234Это исключение собирает исключения, возникающие во время операции с несколькими файлами. Для [`copytree()`](https://python-all.ru/3.9/library/shutil.html#shutil.copytree) аргумент исключения представляет собой список кортежей из трёх элементов (*srcname*, *dstname*, *исключение*).235236### Эффективные операции копирования, зависящие от платформы237238Начиная с Python 3.8 все функции, связанные с копированием файлов ([`copyfile()`](https://python-all.ru/3.9/library/shutil.html#shutil.copyfile), [`copy()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy), [`copy2()`](https://python-all.ru/3.9/library/shutil.html#shutil.copy2), [`copytree()`](https://python-all.ru/3.9/library/shutil.html#shutil.copytree) и [`move()`](https://python-all.ru/3.9/library/shutil.html#shutil.move)), могут использовать платформенно-зависимые системные вызовы «быстрого копирования» для более эффективного копирования файла (см. [bpo-33671](https://python-all.ru/3.9/library/shutil.html)). «Быстрое копирование» означает, что операция копирования происходит внутри ядра, минуя использование буферов пользовательского пространства в Python, как в «`outfd.write(infd.read())`».239240В macOS [fcopyfile](https://python-all.ru/3.9/library/shutil.html) используется для копирования содержимого файла (не метаданных).241242В Linux используется [`os.sendfile()`](https://python-all.ru/3.9/library/os.html#os.sendfile).243244В Windows [`shutil.copyfile()`](https://python-all.ru/3.9/library/shutil.html#shutil.copyfile) использует больший размер буфера по умолчанию (1 МиБ вместо 64 КиБ) и используется вариант [`shutil.copyfileobj()`](https://python-all.ru/3.9/library/shutil.html#shutil.copyfileobj) на основе [`memoryview()`](https://python-all.ru/3.9/library/stdtypes.html#memoryview).245246Если операция быстрого копирования не удалась и в целевой файл не было записано никаких данных, то shutil бесшумно вернется к использованию менее эффективной внутренней функции [`copyfileobj()`](https://python-all.ru/3.9/library/shutil.html#shutil.copyfileobj).247248Изменено в версии 3.8.249250### Пример copytree251252Пример, использующий вспомогательную функцию [`ignore_patterns()`](https://python-all.ru/3.9/library/shutil.html#shutil.ignore_patterns):253254```python255from shutil import copytree, ignore_patterns256257copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))258```259260При этом будет скопировано всё, кроме файлов `.pyc` и файлов или каталогов, имена которых начинаются с `tmp`.261262Ещё один пример, использующий аргумент *ignore* для добавления вызова журналирования:263264```python265from shutil import copytree266import logging267268def _logpath(path, names):269    logging.info('Working in %s', path)270    return []   # ничего не будет проигнорировано271272copytree(source, destination, ignore=_logpath)273```274275### Пример rmtree276277В этом примере показано, как удалить дерево каталогов в Windows, когда у некоторых файлов установлен бит «только для чтения». Он использует колбэк onerror для снятия бита только для чтения и повторной попытки удаления. Любые последующие ошибки будут распространяться.278279```python280import os, stat281import shutil282283def remove_readonly(func, path, _):284    "Clear the readonly bit and reattempt the removal"285    os.chmod(path, stat.S_IWRITE)286    func(path)287288shutil.rmtree(directory, onerror=remove_readonly)289```290291## Операции архивирования292293Новое в версии 3.2.294295Изменено в версии 3.5: Добавлена поддержка формата *xztar*.296297Также предоставляются высокоуровневые утилиты для создания и чтения сжатых и архивных файлов. Они основаны на модулях [`zipfile`](https://python-all.ru/3.9/library/zipfile.html#module-zipfile) и [`tarfile`](https://python-all.ru/3.9/library/tarfile.html#module-tarfile).298299#### `shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])`300301Создаёт архивный файл (например, zip или tar) и возвращает его имя.302303*base\_name* – имя создаваемого файла, включая путь, без формато-специфического расширения. *format* – формат архива: один из «zip» (если доступен модуль [`zlib`](https://python-all.ru/3.9/library/zlib.html#module-zlib)), «tar», «gztar» (если доступен модуль [`zlib`](https://python-all.ru/3.9/library/zlib.html#module-zlib)), «bztar» (если доступен модуль [`bz2`](https://python-all.ru/3.9/library/bz2.html#module-bz2)) или «xztar» (если доступен модуль [`lzma`](https://python-all.ru/3.9/library/lzma.html#module-lzma)).304305*root\_dir* – это каталог, который будет корневым каталогом архива; все пути в архиве будут относительными по отношению к нему; например, перед созданием архива обычно выполняется chdir в *root\_dir*.306307*base\_dir* – это каталог, из которого начинается архивация; т. е. *base\_dir* будет общим префиксом для всех файлов и каталогов в архиве. *base\_dir* должен быть указан относительно *root\_dir*. См. [Пример архивации с base\_dir](https://python-all.ru/3.9/library/shutil.html#shutil-archiving-example-with-basedir) о том, как использовать *base\_dir* и *root\_dir* вместе.308309*root\_dir* и *base\_dir* по умолчанию равны текущему каталогу.310311Если *dry\_run* равен true, архив не создаётся, но операции, которые были бы выполнены, записываются в журнал *logger*.312313*owner* и *group* используются при создании tar-архива. По умолчанию используются текущий владелец и группа.314315*logger* должен быть объектом, совместимым с [**PEP 282**](https://python-all.ru/3.9/library/shutil.html), обычно экземпляром [`logging.Logger`](https://python-all.ru/3.9/library/logging.html#logging.Logger).316317Аргумент *verbose* не используется и является устаревшим.318319Возбуждает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.make_archive` с аргументами `base_name`, `format`, `root_dir`, `base_dir`.320321> **Примечание**322>323> Эта функция не является потокобезопасной.324325Изменено в версии 3.8: Теперь используется современный формат pax (POSIX.1-2001) вместо устаревшего формата GNU для архивов, созданных с помощью `format="tar"`.326327#### `shutil.get_archive_formats()`328329Возвращает список поддерживаемых форматов архивации. Каждый элемент возвращаемой последовательности – это кортеж `(name, description)`.330331По умолчанию [`shutil`](https://python-all.ru/3.9/library/shutil.html#module-shutil) предоставляет следующие форматы:332333- *zip*: ZIP-файл (если доступен модуль [`zlib`](https://python-all.ru/3.9/library/zlib.html#module-zlib)).334- *tar*: Несжатый tar-файл. Использует формат pax (POSIX.1-2001) для новых архивов.335- *gztar*: tar-файл, сжатый gzip (если доступен модуль [`zlib`](https://python-all.ru/3.9/library/zlib.html#module-zlib)).336- *bztar*: tar-файл, сжатый bzip2 (если доступен модуль [`bz2`](https://python-all.ru/3.9/library/bz2.html#module-bz2)).337- *xztar*: tar-файл, сжатый xz (если доступен модуль [`lzma`](https://python-all.ru/3.9/library/lzma.html#module-lzma)).338339Можно зарегистрировать новые форматы или предоставить собственный архиватор для любого существующего формата, используя [`register_archive_format()`](https://python-all.ru/3.9/library/shutil.html#shutil.register_archive_format).340341#### `shutil.register_archive_format(name, function[, extra_args[, description]])`342343Регистрирует архиватор для формата *name*.344345*function* – это вызываемый объект, который будет использоваться для распаковки архивов. Вызываемый объект получает *base\_name* создаваемого файла, за которым следует *base\_dir* (по умолчанию [`os.curdir`](https://python-all.ru/3.9/library/os.html#os.curdir)), откуда начинается архивация. Дополнительные аргументы передаются как именованные: *owner*, *group*, *dry\_run* и *logger* (как передано в [`make_archive()`](https://python-all.ru/3.9/library/shutil.html#shutil.make_archive)).346347Если указан, *extra\_args* – это последовательность пар `(name, value)`, которые будут использоваться как дополнительные именованные аргументы при вызове архиватора.348349*description* используется [`get_archive_formats()`](https://python-all.ru/3.9/library/shutil.html#shutil.get_archive_formats), который возвращает список архиваторов. По умолчанию – пустая строка.350351#### `shutil.unregister_archive_format(name)`352353Удалите имя формата архива *name* из списка поддерживаемых форматов.354355#### `shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])`356357Распаковывает архив. *filename* – это полный путь к архиву.358359*extract\_dir* – имя целевой директории, в которую распаковывается архив. Если не указано, используется текущая рабочая директория.360361*format* – это формат архива: один из «zip», «tar», «gztar», «bztar» или «xztar». Или любой другой формат, зарегистрированный с помощью [`register_unpack_format()`](https://python-all.ru/3.9/library/shutil.html#shutil.register_unpack_format). Если формат не указан, [`unpack_archive()`](https://python-all.ru/3.9/library/shutil.html#shutil.unpack_archive) будет использовать расширение имени файла архива и проверит, зарегистрирован ли распаковщик для этого расширения. Если ничего не найдено, вызывается [`ValueError`](https://python-all.ru/3.9/library/exceptions.html#ValueError).362363Аргумент *filter*, доступный только по ключевому слову и добавленный в Python 3.9.17, передаётся в нижележащую функцию распаковки. Для zip-файлов *filter* не принимается. Для tar-файлов рекомендуется устанавливать его в `'data'`, если только не используются возможности, специфичные для tar и файловых систем, подобных UNIX. (Подробности см. в [Фильтры извлечения](https://python-all.ru/3.9/library/tarfile.html#tarfile-extraction-filter).) Фильтр `'data'` станет фильтром по умолчанию для tar-файлов в Python 3.14.364365Вызывает [событие аудита](https://python-all.ru/3.9/library/sys.html#auditing) `shutil.unpack_archive` с аргументами `filename`, `extract_dir`, `format`.366367> **Предупреждение**368>369> Никогда не извлекайте архивы из ненадежных источников без предварительной проверки. Возможно, файлы будут созданы за пределами пути, указанного в аргументе *extract\_dir*, например, файлы с абсолютными именами, начинающимися с «/», или именами с двумя точками «..».370371Изменено в версии 3.7: Принимает [объект, подобный пути](https://python-all.ru/3.9/glossary.html#term-path-like-object) для *filename* и *extract\_dir*.372373Изменено в версии 3.9.17: Добавлен аргумент *filter*.374375#### `shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])`376377Регистрирует формат распаковки. *name* – имя формата, а *extensions* – список расширений, соответствующих этому формату, например `.zip` для Zip-файлов.378379*function* – вызываемый объект, который будет использоваться для распаковки архивов. Вызываемый объект получит:380381- путь к архиву в качестве позиционного аргумента;382- каталог, в который необходимо извлечь архив, в качестве позиционного аргумента;383- возможно, ключевой аргумент *filter*, если он был передан в [`unpack_archive()`](https://python-all.ru/3.9/library/shutil.html#shutil.unpack_archive);384- дополнительные ключевые аргументы, заданные *extra\_args* в виде последовательности кортежей `(name, value)`.385386*description* может быть указано для описания формата и будет возвращено функцией [`get_unpack_formats()`](https://python-all.ru/3.9/library/shutil.html#shutil.get_unpack_formats).387388#### `shutil.unregister_unpack_format(name)`389390Отменяет регистрацию формата распаковки. *name* – имя формата.391392#### `shutil.get_unpack_formats()`393394Возвращает список всех зарегистрированных форматов для распаковки. Каждый элемент возвращаемой последовательности является кортежем `(name, extensions, description)`.395396По умолчанию [`shutil`](https://python-all.ru/3.9/library/shutil.html#module-shutil) предоставляет следующие форматы:397398- *zip*: ZIP-файл (распаковка сжатых файлов работает, только если доступен соответствующий модуль).399- *tar*: несжатый tar-файл.400- *gztar*: tar-файл, сжатый gzip (если доступен модуль [`zlib`](https://python-all.ru/3.9/library/zlib.html#module-zlib)).401- *bztar*: tar-файл, сжатый bzip2 (если доступен модуль [`bz2`](https://python-all.ru/3.9/library/bz2.html#module-bz2)).402- *xztar*: tar-файл, сжатый xz (если доступен модуль [`lzma`](https://python-all.ru/3.9/library/lzma.html#module-lzma)).403404Вы можете зарегистрировать новые форматы или предоставить собственный распаковщик для любых существующих форматов, используя [`register_unpack_format()`](https://python-all.ru/3.9/library/shutil.html#shutil.register_unpack_format).405406### Пример архивации407408В этом примере мы создаём tar-архив, сжатый gzip, содержащий все файлы, найденные в каталоге `.ssh` пользователя:409410```python411>>> from shutil import make_archive412>>> import os413>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))414>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))415>>> make_archive(archive_name, 'gztar', root_dir)416'/Users/tarek/myarchive.tar.gz'417```418419Полученный архив содержит:420421```console422$ tar -tzvf /Users/tarek/myarchive.tar.gz423drwx------ tarek/staff       0 2010-02-01 16:23:40 ./424-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys425-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config426-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa427-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub428-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa429-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub430-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts431```432433### Пример архивации с *base\_dir*434435В этом примере, аналогичном [предыдущему](https://python-all.ru/3.9/library/shutil.html#shutil-archiving-example), показано, как использовать [`make_archive()`](https://python-all.ru/3.9/library/shutil.html#shutil.make_archive), но на этот раз с применением *base\_dir*. Теперь структура каталогов выглядит так:436437```console438$ tree tmp439tmp440└── root441    └── structure442        ├── content443            └── please_add.txt444        └── do_not_add.txt445```446447В итоговый архив должен быть включён `please_add.txt`, а `do_not_add.txt` – нет. Поэтому используется следующее:448449```python450>>> from shutil import make_archive451>>> import os452>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))453>>> make_archive(454...     archive_name,455...     'tar',456...     root_dir='tmp/root',457...     base_dir='structure/content',458... )459'/Users/tarek/my_archive.tar'460```461462Вывод списка файлов в полученном архиве даёт:463464```console465$ python -m tarfile -l /Users/tarek/myarchive.tar466structure/content/467structure/content/please_add.txt468```469470## Запрос размера выходного терминала471472#### `shutil.get_terminal_size(fallback=(columns, lines))`473474Получить размер окна терминала.475476Для каждого из двух измерений проверяется переменная окружения, соответственно `COLUMNS` и `LINES`. Если переменная определена и её значение – положительное целое число, оно используется.477478Если `COLUMNS` или `LINES` не определена (что бывает чаще всего), терминал, подключённый к [`sys.__stdout__`](https://python-all.ru/3.9/library/sys.html#sys.__stdout__), опрашивается с помощью вызова [`os.get_terminal_size()`](https://python-all.ru/3.9/library/os.html#os.get_terminal_size).479480Если размер терминала не удаётся опросить – либо из-за того, что система не поддерживает опрос, либо потому, что нет подключения к терминалу, – используется значение, указанное в параметре `fallback`. `fallback` по умолчанию равно `(80, 24)`, это размер, используемый по умолчанию многими эмуляторами терминала.481482Возвращаемое значение – именованный кортеж типа [`os.terminal_size`](https://python-all.ru/3.9/library/os.html#os.terminal_size).483484См. также: The Single UNIX Specification, Version 2, [Другие переменные окружения](https://python-all.ru/3.9/library/shutil.html).485486Новое в версии 3.3.487