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

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

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

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

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(). Она игнорирует файлы и каталоги, соответствующие одному из заданных шаблонов patterns в стиле 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().

Если назначение находится в текущей файловой системе, используется os.rename(). В противном случае 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 не задан, значение переменной окружения PATH считывается из os.environ; если переменная не задана, используется 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() аргумент исключения представляет собой список кортежей из 3 элементов (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).

root_dir — каталог, который станет корневым каталогом архива; все пути в архиве будут относительно него. Например, перед созданием архива обычно выполняется переход в 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 не используется и объявлен устаревшим.

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

Можно зарегистрировать новые форматы или предоставить собственный архиватор для любого существующего формата с помощью 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». Также можно указать любой другой формат, зарегистрированный с помощью register_unpack_format(). Если аргумент не задан, unpack_archive() использует расширение имени файла архива и проверяет, зарегистрирован ли распаковщик для этого расширения. Если подходящий распаковщик не найден, возбуждается исключение ValueError.

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

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

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

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

Изменено в версии 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).

Можно зарегистрировать новые форматы или предоставить собственный распаковщик для любого существующего формата с помощью 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() возвращает нули.