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

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

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

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

copyfileobj() не гарантирует, что после завершения копирования целевой поток будет сброшен. Если после завершения операции копирования нужно прочитать данные из целевого файла (например, содержимое временного файла, скопированного из HTTP-потока), перед чтением целевого файла необходимо вызвать flush() или close() для файловоподобного объекта.

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

Скопировать содержимое (без метаданных) файла с именем src в файл с именем dst наиболее эффективным способом и вернуть dst. src и dst — это объекты, подобные путям, или имена путей, заданные в виде строк.

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

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

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

Вызывает событие аудита shutil.copyfile с аргументами src, dst.

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

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

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

exception shutil.SpecialFileError

Это исключение возникает, если copyfile() или copytree() пытается скопировать именованный канал.

Добавлено в версии 2.7.

exception shutil.SameFileError

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

Добавлено в версии 3.4.

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

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

Вызывает событие аудита shutil.copymode с аргументами src, dst.

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

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

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

Если 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.

Вызывает событие аудита shutil.copystat с аргументами src, dst.

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

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

Скопировать файл src в файл или каталог dst. src и dst должны быть объектами, подобными путям, или строками. Если dst указывает на каталог, файл будет скопирован в dst под исходным именем из src. Если dst указывает на уже существующий файл, он будет заменён. Возвращает путь к созданному файлу.

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

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

Вызывает событие аудита shutil.copyfile с аргументами src, dst.

Вызывает событие аудита 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().

Вызывает событие аудита shutil.copyfile с аргументами src, dst.

Вызывает событие аудита 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.

Вызывает событие аудита 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, либо, если не указан ни один из них, исключения передаются вызывающему коду.

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

Примечание

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

Если задан параметр onexc, он должен быть вызываемым объектом, принимающим три параметра: function, path и excinfo.

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

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

См. также

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

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

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

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

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

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

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

rmtree.avoids_symlink_attacks

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

Добавлено в версии 3.3.

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

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

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

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

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

Если источник является символической ссылкой, в месте назначения или в каталоге назначения будет создана новая символическая ссылка, указывающая на цель src, а src будет удалён.

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

Вызывает событие аудита shutil.move с аргументами src, dst.

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

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

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

Изменено в версии 3.9: Для src и dst принимаются объекты, подобные путям.

shutil.disk_usage(path)

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

Примечание

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

Добавлено в версии 3.3.

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

Доступность: Unix, Windows.

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

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

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

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

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

Доступность: Unix.

Добавлено в версии 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», задающая каталоги для поиска, разделённые символом os.pathsep. Если path не указан, из os.environ считывается переменная окружения PATH; если она не задана, используется os.defpath.

Если cmd содержит компонент каталога, which() проверяет только указанный путь и не выполняет поиск в каталогах, перечисленных в path или в системной переменной окружения PATH.

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

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

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

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

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

Добавлено в версии 3.3.

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

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

exception shutil.Error

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

from shutil import copytree, ignore_patterns

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

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)

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)

Операции архивации

Также предоставляются высокоуровневые средства для создания и чтения сжатых архивных файлов. Они используют модули 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) или «zstdtar» (если доступен модуль compression.zstd).

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

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

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

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

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

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

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

Вызывает событие аудита shutil.make_archive с аргументами base_name, format, root_dir, base_dir.

Примечание

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

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

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

shutil.get_archive_formats()

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

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

• zip: ZIP-файл (если доступен модуль zlib).
• tar: несжатый tar-файл. Для новых архивов используется формат POSIX.1-2001 pax.
• gztar: tar-файл, сжатый gzip (если доступен модуль zlib).
• bztar: tar-файл, сжатый bzip2 (если доступен модуль bz2).
• xztar: tar-файл, сжатый xz (если доступен модуль lzma).
• zstdtar: tar-файл, сжатый Zstandard (если доступен модуль compression.zstd).

С помощью 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.supports_root_dir объекта function имеет значение 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 — имя целевого каталога, в который распаковывается архив. Если аргумент не задан, используется текущий рабочий каталог.

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

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

Вызывает событие аудита shutil.unpack_archive с аргументами filename, extract_dir, format.

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

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

Начиная с Python 3.14 настройки по умолчанию для обоих встроенных форматов (ZIP- и tar-файлов) предотвращают наиболее опасные подобные проблемы безопасности, но не исключают все нежелательные последствия. Сведения, относящиеся к tar, см. в разделе Рекомендации по дополнительной проверке.

Изменено в версии 3.7: Для аргументов filename и extract_dir принимается объект, подобный пути.

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

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: tar-файл, сжатый gzip (если доступен модуль zlib).
• bztar: tar-файл, сжатый bzip2 (если доступен модуль bz2).
• xztar: tar-файл, сжатый xz (если доступен модуль lzma).
• zstdtar: tar-файл, сжатый Zstandard (если доступен модуль compression.zstd).

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

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

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── 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/myarchive.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.

См. также: Спецификация Single UNIX, версия 2, раздел Другие переменные окружения.

Добавлено в версии 3.3.

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