shutil.md
1> **Источник:** https://python-all.ru/3.1/library/shutil.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 10.9. `shutil` – высокоуровневые операции с файлами89Модуль `shutil` предоставляет ряд высокоуровневых операций над файлами и наборами файлов. В частности, предоставляются функции для копирования и удаления файлов. Для операций с отдельными файлами см. также модуль [`os`](https://python-all.ru/3.1/library/os.html#module-os).1011> **Предупреждение**12>13> Даже более высокоуровневые функции копирования файлов ([`copy()`](https://python-all.ru/3.1/library/shutil.html#shutil.copy), [`copy2()`](https://python-all.ru/3.1/library/shutil.html#shutil.copy2)) не могут копировать все метаданные файлов.14>15> На платформах POSIX это означает, что владелец и группа файла теряются, а также ACL. На Mac OS не используются ресурсные форки и другие метаданные. Это означает, что ресурсы будут потеряны, а коды типа и создателя файла будут некорректными. В Windows владельцы файлов, ACL и альтернативные потоки данных не копируются.1617#### `shutil.copyfileobj(fsrc, fdst[, length])`1819Копирует содержимое файлоподобного объекта2021*fsrc*2223в файлоподобный объект2425*fdst*2627. Целое число2829*length*3031, если задано, определяет размер буфера. В частности, отрицательное значение3233*length*3435означает копирование данных без разбиения исходных данных на части; по умолчанию данные читаются порциями, чтобы избежать неконтролируемого расхода памяти. Обратите внимание: если текущая позиция в файле объекта3637*fsrc*3839не равна 0, будут скопированы только данные от текущей позиции до конца файла.4041#### `shutil.copyfile(src, dst)`4243Копирует содержимое (без метаданных) файла с именем4445*src*4647в файл с именем4849*dst*5051.5253*dst*5455должно быть полным именем целевого файла; для копирования, принимающего путь к каталогу назначения, используйте5657[`copy()`](https://python-all.ru/3.1/library/shutil.html#shutil.copy)5859. Если6061*src*6263и6465*dst*6667– один и тот же файл, вызывается6869[`Error`](https://python-all.ru/3.1/library/shutil.html#shutil.Error)7071. Целевое местоположение должно быть доступно для записи; в противном случае будет вызвано исключение7273[`IOError`](https://python-all.ru/3.1/library/exceptions.html#IOError)7475. Если7677*dst*7879уже существует, он будет заменён. Специальные файлы, такие как символьные или блочные устройства и каналы, не могут быть скопированы этой функцией.8081*src*8283и8485*dst*8687– имена путей, заданные в виде строк.8889#### `shutil.copymode(src, dst)`9091Копирует биты разрешений из9293*src*9495в9697*dst*9899. Содержимое файла, владелец и группа не изменяются.100101*src*102103и104105*dst*106107– пути, заданные в виде строк.108109#### `shutil.copystat(src, dst)`110111Копирует биты разрешений, время последнего доступа, время последнего изменения и флаги из112113*src*114115в116117*dst*118119. Содержимое файла, владелец и группа не изменяются.120121*src*122123и124125*dst*126127– пути, заданные в виде строк.128129#### `shutil.copy(src, dst)`130131Копирует файл132133*src*134135в файл или каталог136137*dst*138139. Если140141*dst*142143– каталог, в указанном каталоге создаётся (или перезаписывается) файл с тем же базовым именем, что и144145*src*146147. Биты разрешений копируются.148149*src*150151и152153*dst*154155– пути, заданные в виде строк.156157#### `shutil.copy2(src, dst)`158159Аналогична160161[`copy()`](https://python-all.ru/3.1/library/shutil.html#shutil.copy)162163, но копирует также метаданные – по сути, это164165[`copy()`](https://python-all.ru/3.1/library/shutil.html#shutil.copy)166167с последующим вызовом168169[`copystat()`](https://python-all.ru/3.1/library/shutil.html#shutil.copystat)170171. Похожа на команду Unix172173**cp -p**174175.176177#### `shutil.ignore_patterns(*patterns)`178179Эта фабричная функция создаёт функцию, которую можно использовать в качестве вызываемого объекта для180181[`copytree()`](https://python-all.ru/3.1/library/shutil.html#shutil.copytree)182183аргумента184185*ignore*186187, игнорируя файлы и каталоги, соответствующие одному из предоставленных шаблонов в стиле glob188189*patterns*190191. Смотрите пример ниже.192193#### `shutil.copytree(src, dst[, symlinks=False[, ignore=None]])`194195Рекурсивно копирует всё дерево каталогов с корнем в *src*. Целевой каталог, заданный именем *dst*, не должен существовать; он будет создан вместе с недостающими родительскими каталогами. Права доступа и временные метки каталогов копируются с помощью [`copystat()`](https://python-all.ru/3.1/library/shutil.html#shutil.copystat), отдельные файлы копируются с помощью [`copy2()`](https://python-all.ru/3.1/library/shutil.html#shutil.copy2).196197Если *symlinks* равно true, символические ссылки в исходном дереве представляются как символические ссылки в новом дереве; если false или параметр опущен, содержимое файлов, на которые указывают ссылки, копируется в новое дерево.198199Если задан *ignore*, он должен быть вызываемым объектом, который будет получать в качестве аргументов каталог, посещаемый функцией [`copytree()`](https://python-all.ru/3.1/library/shutil.html#shutil.copytree), и список его содержимого, возвращаемый функцией [`os.listdir()`](https://python-all.ru/3.1/library/os.html#os.listdir). Поскольку [`copytree()`](https://python-all.ru/3.1/library/shutil.html#shutil.copytree) вызывается рекурсивно, вызываемый объект *ignore* будет вызываться один раз для каждого копируемого каталога. Вызываемый объект должен возвращать последовательность имён каталогов и файлов относительно текущего каталога (т.е. подмножество элементов своего второго аргумента); эти имена затем будут игнорироваться в процессе копирования. [`ignore_patterns()`](https://python-all.ru/3.1/library/shutil.html#shutil.ignore_patterns) можно использовать для создания такого вызываемого объекта, который игнорирует имена на основе шаблонов в стиле glob.200201Если возникнут исключения, возбуждается исключение [`Error`](https://python-all.ru/3.1/library/shutil.html#shutil.Error) со списком причин.202203Данный исходный код следует рассматривать скорее как пример, а не как универсальный инструмент.204205#### `shutil.rmtree(path[, ignore_errors[, onerror]])`206207Удаляет целое дерево каталогов; *path* должен указывать на каталог (но не на символическую ссылку на каталог). Если *ignore\_errors* равен true, ошибки, возникающие при неудачном удалении, игнорируются; если false или не указан, такие ошибки обрабатываются вызовом обработчика, заданного *onerror*, или, если он не указан, вызывается исключение.208209Если указан *onerror*, это должен быть вызываемый объект, принимающий три параметра: *function*, *path* и *excinfo*. Первый параметр, *function*, – это функция, возбудившая исключение; это может быть [`os.path.islink()`](https://python-all.ru/3.1/library/os.path.html#os.path.islink), [`os.listdir()`](https://python-all.ru/3.1/library/os.html#os.listdir), [`os.remove()`](https://python-all.ru/3.1/library/os.html#os.remove) или [`os.rmdir()`](https://python-all.ru/3.1/library/os.html#os.rmdir). Второй параметр, *path*, – это имя пути, переданное *function*. Третий параметр, *excinfo*, – это информация об исключении, возвращаемая [`sys.exc_info()`](https://python-all.ru/3.1/library/sys.html#sys.exc_info). Исключения, возбуждённые *onerror*, не перехватываются.210211#### `shutil.move(src, dst)`212213Рекурсивно перемещает файл или каталог в другое место.214215Если целевой объект находится в той же файловой системе, просто используется rename. В противном случае src копируется (с помощью [`copy2()`](https://python-all.ru/3.1/library/shutil.html#shutil.copy2)) в dst, а затем src удаляется.216217#### `exception shutil.Error`218219Это исключение собирает исключения, возникшие во время операции с несколькими файлами. Для220221[`copytree()`](https://python-all.ru/3.1/library/shutil.html#shutil.copytree)222223аргумент исключения представляет собой список кортежей из трёх элементов (224225*srcname*226227,228229*dstname*230231,232233*exception*234235).236237## 10.9.1. Пример238239Этот пример является реализацией функции [`copytree()`](https://python-all.ru/3.1/library/shutil.html#shutil.copytree), описанной выше, с опущенной строкой документации. Он демонстрирует многие другие функции, предоставляемые этим модулем.240241```python242def copytree(src, dst, symlinks=False):243 names = os.listdir(src)244 os.makedirs(dst)245 errors = []246 for name in names:247 srcname = os.path.join(src, name)248 dstname = os.path.join(dst, name)249 try:250 if symlinks and os.path.islink(srcname):251 linkto = os.readlink(srcname)252 os.symlink(linkto, dstname)253 elif os.path.isdir(srcname):254 copytree(srcname, dstname, symlinks)255 else:256 copy2(srcname, dstname)257 # XXX Что насчет устройств, сокетов и т.д.?258 except (IOError, os.error) as why:259 errors.append((srcname, dstname, str(why)))260 # перехватываем ошибку от рекурсивного copytree, чтобы мы могли261 # продолжить с другими файлами262 except Error as err:263 errors.extend(err.args[0])264 try:265 copystat(src, dst)266 except WindowsError:267 # не удается скопировать время доступа к файлам в Windows268 pass269 except OSError as why:270 errors.extend((src, dst, str(why)))271 if errors:272 raise Error(errors)273```274