shutil — Высокоуровневые операции с файлами

Источник: Lib/shutil.py

---

Модуль shutil предлагает ряд высокоуровневых операций над файлами и коллекциями файлов. В частности, предоставляются функции, поддерживающие копирование и удаление файлов. Для операций над отдельными файлами см. также модуль os.

Предупреждение

Даже функции копирования файлов более высокого уровня (shutil.copy(), shutil.copy2()) не могут скопировать все метаданные файла.

На платформах POSIX это означает, что владелец и группа файла теряются, равно как и ACL. В Mac OS вилка ресурсов и другие метаданные не используются. Это означает, что ресурсы будут потеряны, а коды типа и создателя файла будут неверными. В Windows владельцы файлов, ACL и альтернативные потоки данных не копируются.

Операции с каталогами и файлами

shutil.copyfileobj(fsrc, fdst[, length])

Скопируйте содержимое file-like object fsrc в файлоподобный объект fdst. Целое число length, если задано, является размером буфера. В частности, отрицательное значение length означает копирование данных без циклического просмотра исходных данных по кускам; по умолчанию данные считываются по кускам, чтобы избежать неконтролируемого потребления памяти. Обратите внимание, что если текущая позиция файла объекта fsrc не равна 0, то будет скопировано только содержимое от текущей позиции файла до его конца.

shutil.copyfile(src, dst, *, follow_symlinks=True)

Скопируйте содержимое (без метаданных) файла с именем src в файл с именем dst и верните dst наиболее эффективным способом. src и dst - это имена path-like objects или пути, заданные в виде строк.

dst должно быть полным именем целевого файла; посмотрите copy() для копии, которая принимает путь к целевому каталогу. Если src и dst указывают на один и тот же файл, будет вызвана SameFileError.

Место назначения должно быть доступно для записи; в противном случае будет вызвано исключение OSError. Если dst уже существует, он будет заменен. Специальные файлы, такие как символьные или блочные устройства и трубы, не могут быть скопированы с помощью этой функции.

Если follow_symlinks равно false и src является символической ссылкой, то вместо копирования файла, на который указывает src, будет создана новая символическая ссылка.

Поднимает auditing event shutil.copyfile с аргументами src, dst.

Изменено в версии 3.3: Раньше вместо IOError поднимался OSError. Добавлен аргумент follow_symlinks. Теперь возвращается dst.

Изменено в версии 3.4: Поднимайте SameFileError вместо Error. Поскольку первый класс является подклассом второго, это изменение совместимо с обратным ходом событий.

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы быстрого копирования. См. раздел Эффективные операции копирования в зависимости от платформы.

exception shutil.SameFileError

Это исключение возникает, если источник и пункт назначения в copyfile() являются одним и тем же файлом.

Added in version 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)

Скопируйте биты разрешения из src в dst. Содержимое файла, владелец и группа не затрагиваются. src и dst - это имена path-like objects или пути, заданные в виде строк. Если follow_symlinks равно false, и оба src и dst являются символическими ссылками, copymode() попытается изменить режим самого dst (а не файла, на который он указывает). Эта функция доступна не на всех платформах; дополнительную информацию см. в copystat(). Если copymode() не может модифицировать символические ссылки на локальной платформе, а его попросят это сделать, он ничего не сделает и вернется.

Поднимает auditing event shutil.copymode с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks.

shutil.copystat(src, dst, *, follow_symlinks=True)

Скопируйте биты разрешения, время последнего доступа, время последней модификации и флаги из src в dst. В Linux copystat() также копирует «расширенные атрибуты», где это возможно. Содержимое файла, владелец и группа не затрагиваются. src и dst - это имена path-like objects или пути, заданные в виде строк.

Если значение follow_symlinks равно false, а src и dst ссылаются на символические ссылки, copystat() будет работать с самими символическими ссылками, а не с файлами, на которые ссылаются символические ссылки - считывать информацию с символической ссылки src и записывать ее в символическую ссылку dst.

Примечание

Не все платформы предоставляют возможность просматривать и изменять символические ссылки. Python сам может подсказать вам, какая функциональность доступна локально.

• Если os.chmod in os.supports_follow_symlinks равно True, то copystat() может изменять биты разрешения символической ссылки.

• Если os.utime in os.supports_follow_symlinks равно True, то copystat() может изменять время последнего доступа и модификации символической ссылки.

• Если os.chflags in os.supports_follow_symlinks равен True, то copystat() может изменять флаги символической ссылки. (os.chflags доступен не на всех платформах).

На платформах, где некоторые или все эти функции недоступны, при запросе на модификацию символической ссылки copystat() скопирует все, что сможет. copystat() никогда не возвращает ошибку.

Дополнительную информацию см. в разделе os.supports_follow_symlinks.

Поднимает auditing event shutil.copystat с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks и поддержка расширенных атрибутов Linux.

shutil.copy(src, dst, *, follow_symlinks=True)

Копирует файл src в файл или каталог dst. src и dst должны быть path-like objects или строками. Если dst указывает каталог, файл будет скопирован в dst с использованием базового имени файла из src. Если в dst указан уже существующий файл, он будет заменен. Возвращает путь к вновь созданному файлу.

Если follow_symlinks равно false и src является символической ссылкой, dst будет создан как символическая ссылка. Если follow_symlinks равно true и src является символической ссылкой, dst будет копией файла, на который ссылается src.

copy() копирует данные файла и режим разрешения файла (см. os.chmod()). Другие метаданные, например время создания и модификации файла, не сохраняются. Чтобы сохранить все метаданные файла из оригинала, используйте вместо этого команду copy2().

Поднимает auditing event shutil.copyfile с аргументами src, dst.

Поднимает auditing event shutil.copymode с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks. Теперь возвращается путь к вновь созданному файлу.

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы быстрого копирования. См. раздел Эффективные операции копирования в зависимости от платформы.

shutil.copy2(src, dst, *, follow_symlinks=True)

Идентично copy(), за исключением того, что copy2() также пытается сохранить метаданные файла.

Если значение follow_symlinks равно false, а src является символической ссылкой, copy2() пытается скопировать все метаданные из символической ссылки src во вновь созданную символическую ссылку dst. Однако эта функциональность доступна не на всех платформах. На платформах, где эта функциональность частично или полностью недоступна, copy2() сохраняет все метаданные, которые может; copy2() никогда не вызывает исключения, поскольку не может сохранить метаданные файла.

copy2() использует copystat() для копирования метаданных файла. Дополнительные сведения о поддержке платформы для изменения метаданных символических ссылок см. в разделе copystat().

Поднимает auditing event shutil.copyfile с аргументами src, dst.

Поднимает auditing event shutil.copystat с аргументами src, dst.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks, пытающийся копировать и расширенные атрибуты файловой системы (пока только для Linux). Теперь возвращает путь к вновь созданному файлу.

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы быстрого копирования. См. раздел Эффективные операции копирования в зависимости от платформы.

shutil.ignore_patterns(*patterns)

Эта фабричная функция создает функцию, которая может быть использована в качестве вызываемой для аргумента ignore в copytree(), игнорируя файлы и каталоги, соответствующие одному из предоставленных шаблонов в стиле glob. Смотрите пример ниже.

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

Рекурсивно скопировать все дерево каталогов с корнем в src в каталог с именем dst и вернуть каталог назначения. Все промежуточные каталоги, необходимые для содержания dst, также будут созданы по умолчанию.

Разрешения и время каталогов копируются с помощью copystat(), отдельные файлы - с помощью copy2().

Если значение symlinks равно true, то символические ссылки в исходном дереве будут представлены как символические ссылки в новом дереве, а метаданные исходных ссылок будут скопированы, насколько это позволяет платформа; если значение false или опущено, то содержимое и метаданные связанных файлов будут скопированы в новое дерево.

Когда symlinks равен false, если файл, на который указывает симлинк, не существует, в конце процесса копирования в список ошибок будет добавлено исключение Error. Вы можете установить необязательный флаг ignore_dangling_symlinks в true, если хотите заглушить это исключение. Обратите внимание, что эта опция не влияет на платформы, не поддерживающие os.symlink().

Если указано ignore, то это должна быть вызываемая переменная, которая будет принимать в качестве аргументов каталог, посещаемый copytree(), и список его содержимого, возвращаемый os.listdir(). Поскольку copytree() вызывается рекурсивно, вызываемая переменная ignore будет вызываться один раз для каждого копируемого каталога. Вызываемый модуль должен возвращать последовательность имен каталогов и файлов относительно текущего каталога (т. е. подмножество элементов во втором аргументе); эти имена будут игнорироваться в процессе копирования. ignore_patterns() может быть использован для создания такого вызываемого файла, который игнорирует имена, основанные на шаблонах в стиле glob.

При возникновении исключения (исключений) выдается сообщение Error со списком причин.

Если задана copy_function, то это должна быть вызываемая функция, которая будет использоваться для копирования каждого файла. Она будет вызвана с исходным путем и путем назначения в качестве аргументов. По умолчанию используется copy2(), но можно использовать любую функцию, поддерживающую ту же сигнатуру (например, copy()).

Если значение dirs_exist_ok равно false (по умолчанию) и dst уже существует, будет выдано сообщение FileExistsError. Если dirs_exist_ok равно true, операция копирования будет продолжена, если она встретит существующие каталоги, а файлы в дереве dst будут перезаписаны соответствующими файлами из дерева src.

Поднимает auditing event shutil.copytree с аргументами src, dst.

Изменено в версии 3.2: Добавлен аргумент copy_function для возможности предоставления пользовательской функции копирования. Добавлен аргумент ignore_dangling_symlinks, чтобы исключить ошибки висячих симлинков, когда symlinks равен false.

Изменено в версии 3.3: Копирование метаданных, когда значение symlinks равно false. Теперь возвращает dst.

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы быстрого копирования. См. раздел Эффективные операции копирования в зависимости от платформы.

Изменено в версии 3.8: Добавлен параметр dirs_exist_ok.

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

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

Эта функция может поддерживать paths relative to directory descriptors.

Примечание

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

Если указан onexc, то это должен быть вызываемый модуль, принимающий три параметра: функция, путь и excinfo.

Первый параметр, function, - это функция, вызвавшая исключение; он зависит от платформы и реализации. Второй параметр, path, - это имя пути, переданное в function. Третий параметр, excinfo, - это исключение, которое было поднято. Исключения, вызванные onexc, не будут перехвачены.

Утратившая актуальность onerror похожа на onexc, за исключением того, что третьим параметром, который она получает, является кортеж, возвращаемый из sys.exc_info().

Поднимает auditing event shutil.rmtree с аргументами path, dir_fd.

Изменено в версии 3.3: Добавлена версия, устойчивая к атакам на симлинки, которая используется автоматически, если платформа поддерживает функции на основе fd.

Изменено в версии 3.8: В Windows больше не будет удаляться содержимое перекрестка каталогов перед удалением самого перекрестка.

Изменено в версии 3.11: Добавлен параметр dir_fd.

Изменено в версии 3.12: Добавлен параметр onexc, устаревший onerror.

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

rmtree.avoids_symlink_attacks

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

Added in version 3.3.

shutil.move(src, dst, copy_function=copy2)

Рекурсивное перемещение файла или каталога (src) в другое место и возвращение места назначения.

Если dst является существующим каталогом или симлинком на каталог, то src будет перемещен в этот каталог. Путь назначения в этом каталоге не должен уже существовать.

Если dst уже существует, но не является каталогом, он может быть перезаписан в зависимости от семантики os.rename().

Если место назначения находится в текущей файловой системе, то используется os.rename(). В противном случае src копируется в место назначения с помощью copy_function и затем удаляется. В случае симлинков в качестве места назначения будет создан новый симлинк, указывающий на цель src, а src будет удален.

Если указана copy_function, она должна быть вызываемой, принимающей два аргумента, src и конечный пункт, и будет использоваться для копирования src в конечный пункт, если os.rename() не может быть использована. Если источником является каталог, вызывается copytree(), передавая ему copy_function. По умолчанию copy_function - это copy2(). Использование copy() в качестве функции_копирования позволяет выполнить перемещение, если невозможно скопировать метаданные, за счет того, что метаданные не копируются.

Поднимает auditing event shutil.move с аргументами src, dst.

Изменено в версии 3.3: Добавлена явная обработка симлинков для чужих файловых систем, что адаптирует ее к поведению mv в GNU. Теперь возвращает dst.

Изменено в версии 3.5: Добавлен аргумент ключевого слова copy_function.

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы быстрого копирования. См. раздел Эффективные операции копирования в зависимости от платформы.

Изменено в версии 3.9: Принимает path-like object как для src, так и для dst.

shutil.disk_usage(path)

Возвращает статистику использования диска по заданному пути в виде named tuple с атрибутами total, used и free, которые представляют собой объем общего, используемого и свободного пространства в байтах. Путь может быть файлом или каталогом.

Примечание

В файловых системах Unix, path должен указывать на путь в монтированном разделе файловой системы. На этих платформах CPython не пытается получить информацию об использовании диска из немонтированных файловых систем.

Added in version 3.3.

Изменено в версии 3.8: В Windows path теперь может быть файлом или каталогом.

Availability: Unix, Windows.

shutil.chown(path, user=None, group=None, *, dir_fd=None, follow_symlinks=True)

Изменение владельца пользователя и/или группы данного пути.

user может быть именем пользователя системы или uid; то же самое относится и к group. Требуется хотя бы один аргумент.

См. также os.chown(), базовая функция.

Поднимает auditing event shutil.chown с аргументами path, user, group.

Availability: Unix.

Added in version 3.3.

Изменено в версии 3.13: Добавлены параметры dir_fd и follow_symlinks.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

Возвращает путь к исполняемому файлу, который будет запущен, если будет вызван заданный cmd. Если cmd не будет вызван, возвращается None.

mode - это маска разрешения, передаваемая в os.access(), по умолчанию определяющая, существует ли файл и является ли он исполняемым.

path - это «PATH строка», задающая список каталогов для поиска. Если path не указан, используются результаты os.environ(), возвращающие либо значение «PATH», либо обратное значение os.defpath.

В Windows текущий каталог добавляется к path, если mode не включает os.X_OK. Если mode включает os.X_OK, то для определения того, следует ли добавлять текущий каталог к path, будет использован Windows API NeedCurrentDirectoryForExePathW. Чтобы не обращаться к текущему рабочему каталогу для поиска исполняемых файлов, установите переменную окружения NoDefaultCurrentDirectoryInExePath.

Также в Windows переменная PATHEXT используется для разрешения команд, которые могут не содержать расширения. Например, если вы вызываете shutil.which("python"), which() будет искать PATHEXT, чтобы узнать, что ему следует искать python.exe в каталогах path. Например, в Windows:

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

Это также применяется, когда cmd - это путь, содержащий компонент каталога:

>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'

Added in version 3.3.

Изменено в версии 3.8: Теперь принимается тип bytes. Если тип cmd равен bytes, то тип результата также равен bytes.

Изменено в версии 3.12: В Windows текущий каталог больше не добавляется к пути поиска, если mode включает os.X_OK и WinAPI NeedCurrentDirectoryForExePathW(cmd) равен false, в противном случае текущий каталог добавляется, даже если он уже находится в пути поиска; PATHEXT теперь используется, даже если cmd включает компонент каталога или заканчивается расширением, которое находится в PATHEXT; и имена файлов, не имеющие расширения, теперь могут быть найдены.

Изменено в версии 3.12.1: В Windows, если mode включает os.X_OK, исполняемые файлы с расширением в PATHEXT будут предпочтительнее, чем исполняемые файлы без соответствующего расширения. Это приближает поведение к поведению Python 3.11.

exception shutil.Error

Это исключение собирает исключения, возникающие при выполнении многофайловой операции. Для copytree() аргумент исключения представляет собой список из 3 кортежей (srcname, dstname, exception).

Эффективные операции копирования в зависимости от платформы

Начиная с Python 3.8, все функции, связанные с копированием файла (copyfile(), copy(), copy2(), copytree() и move()), могут использовать специфичные для платформы системные вызовы «fast-copy» для более эффективного копирования файла (см. bpo-33671). «Быстрое копирование» означает, что операция копирования происходит внутри ядра, что позволяет избежать использования буферов пользовательского пространства в Python, как в «outfd.write(infd.read())».

В macOS fcopyfile используется для копирования содержимого файла (не метаданных).

В Linux используется os.sendfile().

В Windows shutil.copyfile() использует больший размер буфера по умолчанию (1 MiB вместо 64 KiB) и используется memoryview()-ориентированный вариант shutil.copyfileobj().

Если операция быстрого копирования завершилась неудачно и в конечный файл не было записано никаких данных, shutil молча вернется к использованию менее эффективной внутренней функции copyfileobj().

Изменено в версии 3.8.

пример копирования дерева

Пример, в котором используется помощник ignore_patterns():

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

При этом будет скопировано все, кроме файлов .pyc и файлов или каталогов, имя которых начинается с tmp.

Еще один пример, использующий аргумент ignore для добавления вызова журнализации:

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)

Пример rmtree

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

import os, stat
import shutil

def remove_readonly(func, path, _):
    "Clear the readonly bit and reattempt the removal"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onexc=remove_readonly)

Операции архивирования

Added in version 3.2.

Изменено в версии 3.5: Добавлена поддержка формата xztar.

Также предоставляются высокоуровневые утилиты для создания и чтения сжатых и заархивированных файлов. Они опираются на модули zipfile и tarfile.

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

Создайте архивный файл (например, zip или tar) и верните его имя.

base_name - это имя создаваемого файла, включая путь, за вычетом расширения, характерного для конкретного формата.

format - формат архива: один из «zip» (если доступен модуль zlib), «tar», «gztar» (если доступен модуль zlib), «bztar» (если доступен модуль bz2) или «xztar» (если доступен модуль lzma).

root_dir - это каталог, который будет корневым каталогом архива, все пути в архиве будут относительными к нему; например, перед созданием архива мы обычно делаем chdir в root_dir.

base_dir - это каталог, из которого мы начинаем архивирование; т.е. base_dir будет общим префиксом всех файлов и каталогов в архиве. base_dir должен быть указан относительно root_dir. Как использовать base_dir и root_dir вместе, смотрите в Пример архивирования с помощью base_dir..

По умолчанию root_dir и base_dir указывают на текущий каталог.

Если значение dry_run равно true, архив не создается, но операции, которые были бы выполнены, записываются в logger.

owner и group используются при создании tar-архива. По умолчанию используется текущий владелец и группа.

logger должен быть объектом, совместимым с PEP 282, обычно это экземпляр logging.Logger.

Аргумент verbose не используется и является устаревшим.

Поднимает auditing event shutil.make_archive с аргументами base_name, format, root_dir, base_dir.

Примечание

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

Изменено в версии 3.8: Современный формат pax (POSIX.1-2001) теперь используется вместо устаревшего формата GNU для архивов, созданных с помощью format="tar".

Изменено в версии 3.10.6: Теперь эта функция стала потокобезопасной при создании стандартных .zip и tar-архивов.

shutil.get_archive_formats()

Возвращает список поддерживаемых форматов для архивирования. Каждый элемент возвращаемой последовательности представляет собой кортеж (name, description).

По умолчанию shutil предоставляет эти форматы:

• zip: ZIP-файл (если доступен модуль zlib).

• tar: Несжатый tar-файл. Использует формат POSIX.1-2001 pax для новых архивов.

• gztar: gzip’ed tar-файла (если доступен модуль zlib).

• bztar: bzip2’ed tar-файл (если доступен модуль bz2).

• xztar: xz’ed tar-файл (если доступен модуль lzma).

Вы можете зарегистрировать новые форматы или предоставить свой собственный архиватор для любых существующих форматов, используя register_archive_format().

shutil.register_archive_format(name, function[, extra_args[, description]])

Зарегистрируйте архиватор для формата name.

function - это вызываемая функция, которая будет использоваться для распаковки архивов. В вызываемую функцию передается имя base_name файла, который нужно создать, затем base_dir (по умолчанию os.curdir), из которого нужно начать архивирование. Дополнительные аргументы передаются в виде ключевых слов: owner, group, dry_run и logger (как передано в make_archive()).

Если для function пользовательский атрибут function.supports_root_dir установлен в True, аргумент root_dir передается как аргумент ключевого слова. В противном случае перед вызовом function текущий рабочий каталог процесса временно меняется на root_dir. В этом случае make_archive() не является потокобезопасным.

Если задано, extra_args - это последовательность пар (name, value), которые будут использоваться в качестве дополнительных аргументов ключевых слов при использовании вызываемого архиватора.

description используется get_archive_formats(), который возвращает список архиваторов. По умолчанию это пустая строка.

Изменено в версии 3.12: Добавлена поддержка функций, поддерживающих аргумент root_dir.

shutil.unregister_archive_format(name)

Удалите формат архива name из списка поддерживаемых форматов.

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

Распаковать архив. filename - полный путь к архиву.

extract_dir - имя целевого каталога, в который распаковывается архив. Если имя не указано, используется текущий рабочий каталог.

формат - формат архива: один из «zip», «tar», «gztar», «bztar» или «xztar». Или любой другой формат, зарегистрированный с помощью register_unpack_format(). Если не указано, unpack_archive() будет использовать расширение имени файла архива и проверять, зарегистрирован ли распаковщик для этого расширения. Если таковой не найден, будет выдан сигнал ValueError.

Аргумент filter, содержащий только ключевое слово, передается базовой функции распаковки. Для zip-файлов filter не принимается. Для файлов tar рекомендуется задавать значение 'data', если только не используются функции, специфичные для tar и UNIX-подобных файловых систем. (Подробнее см. Фильтры для извлечения.) Фильтр 'data' станет фильтром по умолчанию для tar-файлов в Python 3.14.

Поднимает auditing event shutil.unpack_archive с аргументами filename, extract_dir, format.

Предупреждение

Никогда не извлекайте архивы из ненадежных источников без предварительной проверки. Возможно, что файлы создаются вне пути, указанного в аргументе extract_dir, например, члены, абсолютные имена которых начинаются с «/» или имена с двумя точками «.».

Изменено в версии 3.7: Принимает значение path-like object для filename и extract_dir.

Изменено в версии 3.12: Добавлен аргумент фильтр.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

Регистрирует формат распаковки. name - это имя формата, а extensions - список расширений, соответствующих формату, например .zip для Zip-файлов.

function - это вызываемая функция, которая будет использоваться для распаковки архивов. Вызываемая функция будет получать:

• путь к архиву в качестве позиционного аргумента;

• каталог, в который должен быть распакован архив, в качестве позиционного аргумента;

• возможно, аргумент ключевого слова filter, если он был задан в unpack_archive();

• дополнительные аргументы ключевого слова, заданные extra_args в виде последовательности кортежей (name, value).

Для описания формата можно указать description, которая будет возвращена функцией get_unpack_formats().

shutil.unregister_unpack_format(name)

Снять с регистрации формат распаковки. name - имя формата.

shutil.get_unpack_formats()

Возвращает список всех зарегистрированных форматов для распаковки. Каждый элемент возвращаемой последовательности представляет собой кортеж (name, extensions, description).

По умолчанию shutil предоставляет эти форматы:

• zip: ZIP-файл (распаковка сжатых файлов работает только при наличии соответствующего модуля).

• tar: несжатый tar-файл.

• gztar: gzip’ed tar-файла (если доступен модуль zlib).

• bztar: bzip2’ed tar-файл (если доступен модуль bz2).

• xztar: xz’ed tar-файл (если доступен модуль lzma).

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

Пример архивации

В этом примере мы создадим gzip’ed tar-архив, содержащий все файлы, найденные в каталоге .ssh пользователя:

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

Полученный архив содержит:

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

Пример архивирования с помощью base_dir.

В этом примере, аналогичном one above, мы покажем, как использовать make_archive(), но на этот раз с использованием base_dir. Теперь у нас есть следующая структура каталогов:

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

В итоговом архиве please_add.txt должен быть включен, а do_not_add.txt - нет. Поэтому мы используем следующее:

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/my_archive.tar'

Перечисление файлов в полученном архиве дает нам:

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

Запрос размера выходного терминала

shutil.get_terminal_size(fallback=(columns, lines))

Получение размера окна терминала.

Для каждого из двух измерений проверяется переменная окружения, COLUMNS и LINES соответственно. Если переменная определена и ее значение является положительным целым числом, она используется.

Если COLUMNS или LINES не определены, что является обычным случаем, терминал, подключенный к sys.__stdout__, запрашивается путем вызова os.get_terminal_size().

Если размер терминала не может быть успешно запрошен, либо потому что система не поддерживает запрос, либо потому что мы не подключены к терминалу, используется значение, указанное в параметре fallback. По умолчанию fallback принимает значение (80, 24), которое используется по умолчанию во многих эмуляторах терминалов.

Возвращаемое значение - именованный кортеж типа os.terminal_size.

См. также: Единая спецификация UNIX, версия 2, Other Environment Variables.

Added in version 3.3.

Изменено в версии 3.11: Значения fallback также используются, если os.get_terminal_size() возвращает нули.