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

Исходный код: Lib/shutil.py


Модуль shutil предлагает ряд высокоуровневых операций с файлами и коллекциями файлов. В частности, предусмотрены функции, поддерживающие копирование и удаление файлов. Для операций с отдельными файлами см. также модуль os.

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

Даже функции копирования файлов более высокого уровня (shutil.copy(), shutil.copy2()) не могут скопировать все метаданные файла.

На платформах POSIX это означает, что теряются владелец файла и группа, а также списки управления доступом (ACL). В Mac OS вилка (fork) ресурса и другие метаданные не используются. Это означает, что ресурсы будут потеряны, а тип файла и коды создателя будут неправильными. В Windows владельцы файлов, списки управления доступом и альтернативные потоки данных не копируются.

Каталоги и файловые операции

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

Если у 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 ложно, а 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 ложно, а src и dst относятся к символическим ссылкам, copystat() будет работать с самими символическими ссылками, а не с файлами, на которые они ссылаются, — считывая информацию из символической ссылки src и записывая информацию в символическую ссылку dst.

Примечание

Не все платформы предоставляют возможность проверять и изменять символические ссылки. Сам Python может сказать вам, какие функции доступны локально.

  • Если os.chmod in os.supports_follow_symlinksTrue, copystat() может изменять биты разрешения символической ссылки.
  • Если os.utime in os.supports_follow_symlinksTrue, copystat() может изменить время последнего доступа и модификации символической ссылки.
  • Если os.chflags in os.supports_follow_symlinksTrue, 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. Возвращает путь к вновь созданному файлу.

Если follow_symlinks является ложным, а src является символической ссылкой, dst будет создан как символическая ссылка. Если follow_symlinks истинно, а 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)

Эта функция фабрика создаёт функцию, которую можно использовать как вызываемую для аргумента copytree() ignore, игнорируя файлы и каталоги, которые соответствуют одному из предоставленных patterns в стиле glob. См. пример ниже.

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

Рекурсивно скопировать все дерево каталогов с корнем src в каталог с именем dst и вернуть целевой каталог. dirs_exist_ok указывает, вызывать ли исключение в случае, если dst или какой-либо отсутствующий родительский каталог уже существует.

Разрешения и время каталогов копируются с помощью copystat(), отдельные файлы копируются с помощью copy2().

Если symlinks истинно, символические ссылки в исходном дереве представлены как символические ссылки в новом дереве, и метаданные исходных ссылок будут скопированы, насколько позволяет платформа; если ложь или пропущено, содержимое и метаданные связанных файлов копируются в новое дерево.

Когда symlinks имеет ложное значение, если файл, на который указывает символическая ссылка, не существует, исключение будет добавлено в список ошибок, возникших в исключении Error в конце процесса копирования. Вы можете установить для необязательного флага ignore_dangling_symlinks значение истина, если хотите отключить это исключение. Обратите внимание, что этот параметр не действует на платформах, не поддерживающих os.symlink().

Если предоставлен ignore, он должен быть вызываемым, который получит в качестве аргументов каталог, который посещает copytree(), и список его содержимого, возвращенный os.listdir(). Поскольку copytree() вызывается рекурсивно, вызываемый объект ignore будет вызываться один раз для каждого копируемого каталога. Вызываемый объект должен возвращать последовательность имён каталогов и файлов относительно текущего каталога (т. е. подмножество элементов во втором аргументе); эти имена будут проигнорированы в процессе копирования. ignore_patterns() можно использовать для создания такого вызываемого объекта, который игнорирует имена на основе шаблонов стиля glob.

Если возникает исключение (я), возникает Error со списком причин.

Если задан copy_function, он должен быть вызываемым, который будет использоваться для копирования каждого файла. Он будет вызываться с исходным и целевым путём в качестве аргументов. По умолчанию используется copy2(), но можно использовать любую функцию, поддерживающую такую же сигнатуру (например, copy()).

Поднимает событие аудита shutil.copytree с аргументами src, dst.

Изменено в версии 3.3: Копировать метаданные, если symlinks ложно. Теперь возвращает dst.

Изменено в версии 3.2: Добавлен аргумент copy_function, чтобы иметь возможность предоставлять настраиваемую функцию копирования. Добавлен аргумент ignore_dangling_symlinks для ошибок скрытых висячих символических ссылок, когда symlinks имеет ложное значение.

Изменено в версии 3.8: Могут использоваться внутри системы системные вызовы быстрого копирования конкретной платформы для более эффективного копирования файла. См. раздел Зависящие от платформы эффективные операции копирования.

Добавлено в версии 3.8: Параметр dirs_exist_ok.

shutil.rmtree(path, ignore_errors=False, onerror=None)

Удалить все дерево каталогов; path должен указывать на каталог (но не на символическую ссылку на каталог). Если ignore_errors истинно, ошибки, возникающие в результате неудачного удаления, будут игнорироваться; если ложь или пропущено, такие ошибки обрабатываются путём вызова обработчика, указанного в onerror, или, если он пропущен, они вызывают исключение.

Примечание

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

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

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

Поднимает событие аудита shutil.rmtree с аргументом path.

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

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

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

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

shutil.move(src, dst, copy_function=copy2)

Рекурсивно переместить файл или каталог (src) в другое место (dst) и вернуть место назначения.

Если местом назначения является существующий каталог, то src перемещается внутрь этого каталога. Если место назначения уже существует, но не является каталогом, оно может быть перезаписано в зависимости от семантики os.rename().

Если место назначения находится в текущей файловой системе, используется os.rename(). В противном случае src копируется в dst с использованием copy_function, а затем удаляется. В случае символических ссылок новая символическая ссылка, указывающая на цель src, будет создана в или как dst и src будут удалены.

Если задан copy_function, он должен быть вызываемым, который принимает два аргумента src и dst и будет использоваться для копирования src в dst, если os.rename() не может быть использован. Если источником является каталог, вызывается copytree(), передавая ему copy_function(). По умолчанию copy_functioncopy2(). Использование copy() в качестве copy_function позволяет перемещению быть успешным, когда невозможно также скопировать метаданные за счет отсутствия копирования каких-либо метаданных.

Поднимает событие аудита shutil.move с аргументами src, dst.

Изменено в версии 3.3: Добавлена явная обработка символических ссылок для сторонних файловых систем, что позволяет адаптировать её к поведению GNU mv. Теперь возвращает dst.

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

Изменено в версии 3.8: Могут использоваться внутри системы системные вызовы быстрого копирования конкретной платформы для более эффективного копирования файла. См. раздел Зависящие от платформы эффективные операции копирования.

shutil.disk_usage(path)

Возвращает статистику использования диска по заданному пути в виде именованного кортежа с атрибутами total, used и free, которые представляют собой общий объём, использованное и свободное пространство в байтах. path может быть файлом или каталогом.

Добавлено в версии 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 независимо от того, используете ли вы каталог по умолчанию или предоставляете свой собственный, что является поведением командной оболочки при поиске исполняемых файлов. Кроме того, при нахождении cmd в path проверяется переменная среды PATHEXT. Например, если вы вызовите shutil.which("python"), which() будет искать PATHEXT, чтобы знать, что он должен искать python.exe в каталогах path. Например, в Windows:

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

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

Изменено в версии 3.8: Теперь принимается тип bytes. Если тип cmdbytes, тип результата также будет bytes.

exception shutil.Error

Это исключение собирает исключения, возникающие во время операции с несколькими файлами. Для copytree() аргумент исключения представляет собой список из трех кортежей (srcname, dstname, exception).

Операции эффективного копирования, зависящие от платформы

Начиная с Python 3.8, все функции, связанные с копированием файла (copyfile(), copy(), copy2(), copytree() и move()), могут использовать системные вызовы «быстрого копирования» для конкретной платформы для более эффективного копирования файла (см. bpo-33671). «быстрое копирование» означает, что операция копирования происходит внутри ядра, избегая использования буферов пользовательского пространства в Python, как в «outfd.write(infd.read())».

В macOS fcopyfile используется для копирования содержимого файла (не метаданных).

В Linux используется os.sendfile().

В Windows shutil.copyfile() использует больший размер буфера по умолчанию (1 MiB вместо 64 KiB) и вариант shutil.copyfileobj() на основе memoryview().

Если операция быстрого копирования завершилась неудачно и в целевой файл не было записано никаких данных, shutil автоматически откатится на внутреннюю менее эффективную функцию copyfileobj().

Изменено в версии 3.8.

Пример copytree

Этот пример представляет собой реализацию функции copytree(), описанной выше, с пропущенной строкой документации. Он демонстрирует многие другие функции, предоставляемые этим модулем.

def copytree(src, dst, symlinks=False):
    names = os.listdir(src)
    os.makedirs(dst)
    errors = []
    for name in names:
        srcname = os.path.join(src, name)
        dstname = os.path.join(dst, name)
        try:
            if symlinks and os.path.islink(srcname):
                linkto = os.readlink(srcname)
                os.symlink(linkto, dstname)
            elif os.path.isdir(srcname):
                copytree(srcname, dstname, symlinks)
            else:
                copy2(srcname, dstname)
            # XXX Что относительно устройств, сокеты и т.д.?
        except OSError as why:
            errors.append((srcname, dstname, str(why)))
        # ловить ошибку из рекурсивного копировального дерева, чтобы можно было продолжить
        # работу с другими файлами
        except Error as err:
            errors.extend(err.args[0])
    try:
        copystat(src, dst)
    except OSError as why:
        # не удается скопировать время доступа к файлам в Windows
        if why.winerror is None:
            errors.extend((src, dst, str(why)))
    if errors:
        raise Error(errors)

Ещё один пример, в котором используется помощник ignore_patterns():

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

Скопирует всё, кроме файлов .pyc и файлов или каталогов, имена которых начинаются с tmp.

Другой пример, в котором для добавления вызова журнала используется аргумент ignore:

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # ничто не будет проигнорировано

copytree(source, destination, ignore=_logpath)

Пример rmtree

В этом примере показано, как удалить дерево каталогов в Windows, в котором для некоторых файлов установлен бит только для чтения. Он использует обратный вызов onerror, чтобы очистить бит только для чтения и повторить попытку удаления. Любой последующий сбой будет распространяться.

import os, stat
import shutil

def remove_readonly(func, path, _):
    "Очистить бит readonly и повторите попытку удаления."
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onerror=remove_readonly)

Архивные операции

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

Изменено в версии 3.5: Добавлена поддержка формата xztar.

Также предоставляются высокоуровневые утилиты для создания и чтения сжатых и заархивированных файлов. Они полагаются на модули 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 истинно, архив не создаётся, но выполняемые операции записываются в logger.

owner и group используются при создании tar-архива. По умолчанию используется текущий владелец и группа.

logger должен быть объектом, совместимым с PEP 282, обычно экземпляром logging.Logger.

Аргумент verbose не используется и не рекомендуется.

Поднимает событие аудита shutil.make_archive с аргументами base_name, format, root_dir, base_dir.

Изменено в версии 3.8: Теперь используется современный формат pax (POSIX.1-2001) вместо устаревшего формата GNU для архивов, созданных с помощью format="tar".

shutil.get_archive_formats()

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

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

  • zip: ZIP-файл (если доступен модуль zlib).
  • tar: несжатый tar файл. Используется pax формат POSIX.1-2001 для новых архивов.
  • gztar: gzip tar-файл (если модуль zlib доступен).
  • bztar: bzip2 tar-файл (если модуль bz2 доступен).
  • xztar: xz 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()).

Если задано, extra_args представляет собой последовательность пар (name, value), которые будут использоваться в качестве дополнительных ключевых аргументов при использовании вызываемого архиватора.

description используется get_archive_formats(), который возвращает список архиваторов. По умолчанию пустая строка.

shutil.unregister_archive_format(name)

Удалить архив формата name из списка поддерживаемых форматов.

shutil.unpack_archive(filename[, extract_dir[, format]])

Распаковать архив. filename — это полный путь к архиву.

extract_dir — это имя целевого каталога, в который распаковывается архив. Если не указан, используется текущий рабочий каталог.

format — это формат архива: zip, tar, gztar, bztar или xztar. Или любой другой формат, зарегистрированный в register_unpack_format(). Если не указано, unpack_archive() будет использовать расширение имени файла архива и проверять, зарегистрирован ли распаковщик для этого расширения. Если ничего не найдено, поднимается ValueError.

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

Изменено в версии 3.7: Принимает путеподобный объект для filename и extract_dir.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

Регистрирует формат распаковки. name — это имя формата, а extensions — это список расширений, соответствующих формату, например .zip для Zip файлов.

function — это вызываемый объект, который будет использоваться для распаковки архивов. Вызываемый объект получит путь к архиву, за которым следует каталог, в который должен быть извлечён архив.

Если предоставлено, 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().

Пример архивации

В этом примере мы создаем gzip-архив tar-файла, содержащий все файлы, найденные в каталоге .ssh пользователя:

>>> 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

Пример архивации с base_dir

В этом примере, аналогичному вышеуказанному, мы показываем, как использовать make_archive(), но на этот раз с использованием base_dir. Теперь у нас есть следующая структура каталогов:

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

В финальном архиве должен быть 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.

См. также: Единая спецификация UNIX, версия 2, Другие переменные среды.

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