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: Возможно, будут использоваться платформенно-специфические системные вызовы для быстрой копирования, чтобы скопировать файл более эффективно. См. раздел «os.chflags платформенно-зависимые эффективные операции копирования».

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() не может изменить символьные ссылки на локальной платформе, он ничего не сделает и вернёт None.

Вызывает событие аудита аудита 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: Возможно, будут использоваться платформенно-специфические системные вызовы для быстрой копирования, чтобы скопировать файл более эффективно. См. раздел «os.chflags платформенно-зависимые эффективные операции копирования».

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

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

Примечание

На платформах, поддерживающих необходимые функции на основе 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.

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: Добавлена явная обработка символических ссылок для внешних файловых систем, таким образом, адаптирована к поведению mv GNU. Теперь возвращает 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 не указан, используются результаты os.environ(), возвращая либо значение «PATH», либо резервное значение 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; и теперь можно находить имена файлов без расширения.

Изменено в версии 3.12.1: В Windows, если mode включает os.X_OK, исполняемые файлы с расширением из PATHEXT будут предпочтительнее исполняемых файлов без соответствующего расширения. Это приближает поведение к поведению Python 3.11.

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-файл. Для новых архивов используется формат pax POSIX.1-2001.
• 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, версия 2, Другие переменные окружения.

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

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