shutil – высокоуровневые операции с файлами¶shutil – High-level file operations

Операции с каталогами и файлами¶Directory and files operations

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¶

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

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

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

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

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

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

rmtree.avoids_symlink_attacks¶

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

Добавлено в версии 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, то будет вызван Windows API NeedCurrentDirectoryForExePathW, чтобы определить, следует ли добавлять текущий каталог в начало path. Чтобы избежать обращения к текущему рабочему каталогу для исполняемых файлов: установите переменную окружения NoDefaultCurrentDirectoryInExePath.

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

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

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

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

Добавлено в версии 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, исключение).

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 []   # ничего не будет проигнорировано

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)

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

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

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

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

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

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

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

base_dir – это каталог, из которого начинается архивация; т. е. base_dir будет общим префиксом для всех файлов и каталогов в архиве. base_dir должен быть указан относительно root_dir. См. Пример архивации с base_dir о том, как использовать 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: Теперь используется современный формат pax (POSIX.1-2001) вместо устаревшего формата GNU для архивов, созданных с помощью format="tar".

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

shutil.get_archive_formats()¶

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

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

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

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

• 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 есть пользовательский атрибут 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: 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

Запрос размера выходного терминала¶Querying the size of the output terminal

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

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

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

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

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

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

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

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

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