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

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 является ложным, а 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. Возвращает путь к вновь созданному файлу.

Если follow_symlinks имеет значение false, а 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: Определенная для платформы быстрая копия cистемные вызовы может быть используемый внутренне, чтобы скопировать файл более эффективно. См. раздел Зависящие от платформы эффективные операции копирования.

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

shutil.ignore_patterns(*patterns)

Эта функция фабрика создает функцию, которая может быть используемый как подлежащим выкупу для аргумента :func:copytree ignore, игнорируя файлы и справочники, которые соответствуют одному из glob-стиля обеспеченный patterns. См. пример ниже.

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 — истинные, символические ссылки в исходном дереве, представлены как символические ссылки в новом дереве, и метаданные оригинальных ссылок будут скопированы насколько платформа позволяет; если значение равно false или опущено, содержимое и метаданные связанных файлов копируются в новое дерево.

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

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

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

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

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

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

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

Изменено в версии 3.8: Определенная для платформы быстрая копия cистемные вызовы может быть используемый внутренне, чтобы скопировать файл более эффективно.

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

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

Удаление всего дерева каталогов; path должен указывать на каталог (но не на символическую ссылку на каталог). Если ignore_errors будет верен, то ошибки, следующие из неудавшихся удалений, будут проигнорированы; если значение равно false или опущено, такие ошибки обрабатываются путем вызова обработчик, указанного параметром 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.avoids_symlink_attacks

Указывает, обеспечивают ли текущая платформа и внедрение, символическая ссылка нападают на стойкую версию 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_function — copy2(). Использование copy() в качестве copy_function позволяет перемещению быть успешным, когда невозможно также скопировать метаданные за счет отсутствия копирования каких-либо метаданных.

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

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

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

Изменено в версии 3.8: Определенная для платформы быстрая копия cистемные вызовы может быть используемый внутренне, чтобы скопировать файл более эффективно.

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 теперь принят. Если тип cmd — bytes, тип результата — также bytes.

exception shutil.Error

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

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)

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, _):
    "Очистить бит readonly и повторите попытку удаления."
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onerror=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 — это каталог, который будет корневым каталогом архива, все пути в архиве будут относительными; например, мы обычно 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 являются используемый при создании архива смол. По умолчанию использует текущего владельца и группу.

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

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().

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

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

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

источник