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

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

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 — это объекты, подобные путям, либо имена путей, заданные строками.

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.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 будет вызываться для каждого копируемого каталога. Вызываемый объект должен возвращать последовательность имён каталогов и файлов относительно текущего каталога (то есть подмножество элементов второго аргумента); эти имена будут игнорироваться в процессе копирования. Для создания такого вызываемого объекта, игнорирующего имена по шаблонам в стиле glob, можно использовать ignore_patterns().

Если возникает одно или несколько исключений, возбуждается исключение 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().

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

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

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

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

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

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)

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

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

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

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

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

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

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.

В Windows текущий каталог добавляется в начало path, если mode не включает os.X_OK. Если mode включает os.X_OK, для определения того, нужно ли добавлять текущий каталог в начало path, проверяется API Windows 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).

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: Теперь вместо устаревшего формата GNU для архивов, созданных с помощью format="tar", используется современный формат 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-подобных файловых систем. (Подробнее см. раздел Фильтры распаковки.) Фильтр '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: файл 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/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, версия 2, раздел Другие переменные окружения.

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

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