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: IOError использовался вместо OSError. Добавлен аргумент follow_symlinks. Теперь возвращает dst.

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

Изменено в версии 3.8: Внутренне могут использоваться платформенно-зависимые вызовы для быстрой копирования, чтобы более эффективно скопировать файл. См. раздел «exception shutil.SameFileError платформенно-зависимые операции с быстрой копией».

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) платформенно-зависимые операции с быстрой копией».

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

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

Примечание

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

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

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

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

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

Добавлен в версии 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's mv. Теперь возвращает dst.

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

Изменено в версии 3.8: Внутренне могут использоваться платформоспецифические системные вызовы быстрой копирования, чтобы более эффективно скопировать файл. См. раздел Platform-dependent efficient copy operations.

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

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

Также в Windows используется переменная окружения PATHEXT для разрешения команд, которые могут не содержать расширение. Например, если вы вызываете shutil.which("python"), which() будет искать PATHEXT в каталогах path. Например, в 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) ложно, в противном случае текущий каталог добавляется даже если он уже в пути поиска; 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 для того, как использовать 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", теперь используется современный формат pax (POSIX.1-2001) вместо устаревшего формата GNU.

Изменено в версии 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 передаётся как ключевой аргумент. В противном случае текущая рабочая директория процесса временно изменяется на root_dir перед вызовом function. В этом случае 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-подобных файловых систем. (См. Фильтры извлечения для получения подробностей.) Фильтр 'data' станет по умолчанию для tar-файлов в Python 3.14.

Вызывает событие аудита 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: сжатый gzip файл tar (если модуль zlib доступен).
• bztar: сжатый bzip2 файл tar (если модуль bz2 доступен).
• xztar: сжатый xz файл tar (если модуль 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/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.

См. также: Описание Single UNIX Specification, версия 2, Другие переменные окружения.

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

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