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

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

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

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

shutil.copyfileobj(fsrc, fdst[, length])

Копирует содержимое объекта fsrc типа «подобный файлу» в объект fdst типа «подобный файлу». Целое число length, если задано, — размер буфера. В частности, отрицательное значение length означает копирование данных без циклирования по данным источника частями; по умолчанию данные читаются частями, чтобы избежать неконтролируемого потребления памяти. Обратите внимание, что если текущая позиция файла объекта fsrc не 0, будут скопированы только данные от текущей позиции файла до конца файла.

shutil.copyfile(src, dst, *, follow_symlinks=True)

Копирует содержимое (без метаданных) файла с именем src в файл с именем dst и возвращает dst. src и dst — имена путей, заданные в виде строк. dst должен быть полным именем целевого файла; см. shutil.copy() для копирования в целевой каталог. Если src и dst указывают на один и тот же файл, будет поднято исключение SameFileError.

Целевой путь должен быть доступен для записи; в противном случае будет поднято исключение OSError. Если dst уже существует, он будет перезаписан. Специальные файлы, такие как символьные или блочные устройства и каналы, не могут быть скопированы с помощью этой функции.

Если follow_symlinks ложно, а src — символическая ссылка, будет создана новая символическая ссылка вместо копирования файла, на который указывает src.

Изменено в версии 3.3: IOError ранее использовался вместо OSError. Добавлен аргумент follow_symlinks. Теперь возвращает dst.

Изменено в версии 3.4: Поднимается исключение SameFileError вместо Error. Поскольку первое является подклассом второго, это изменение совместимо с более ранними версиями.

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

Изменено в версии 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 для получения дополнительной информации.

Изменено в версии 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().

Изменено в версии 3.3: Добавлен аргумент follow_symlinks. Теперь возвращает путь к новосозданному файлу.

shutil.copy2(src, dst, *, follow_symlinks=True)

Идентично copy(), за исключением того, что copy2() также пытается сохранить все метаданные файла.

Когда follow_symlinks ложно, а src — символическая ссылка, copy2() пытается скопировать все метаданные из символической ссылки src в новую символическую ссылку dst. Однако эта функциональность недоступна на всех платформах. На платформах, где часть или вся эта функциональность недоступна, copy2() сохранит все доступные метаданные; copy2() никогда не возвращает ошибку.

copy2() использует copystat() для копирования метаданных файла. См. copystat() для получения дополнительной информации о поддержке платформы изменения метаданных символических ссылок.

Изменено в версии 3.3: Добавлен аргумент follow_symlinks, попытка скопировать расширенные атрибуты файловой системы (сейчас только Linux). Теперь возвращает путь к новосозданному файлу.

shutil.ignore_patterns(*patterns)

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

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

Рекурсивно копирует всю древовидную структуру каталога, укоренённую в src, возвращая целевой каталог. Целевой каталог, именованный dst, не должен уже существовать; он будет создан, а также отсутствующие родительские каталоги. Разрешения и временные метки каталогов копируются с помощью copystat(), отдельные файлы копируются с помощью shutil.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, она должна быть вызываемым объектом, который будет использоваться для копирования каждого файла. Она будет вызываться с путями источника и назначения в качестве аргументов. По умолчанию используется shutil.copy2(), но может быть использована любая функция, поддерживающая ту же сигнатуру (например, shutil.copy()).

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

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

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

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

Примечание

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

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

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

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

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

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

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

shutil.disk_usage(path)

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

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

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

shutil.chown(path, user=None, group=None)

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

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

См. также os.chown(), функцию-аналог.

Доступность: 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.

exception shutil.Error

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

1.1. пример 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 What about devices, sockets etc.?
        except OSError as why:
            errors.append((srcname, dstname, str(why)))
        # catch the Error from the recursive copytree so that we can
        # continue with other files
        except Error as err:
            errors.extend(err.args[0])
    try:
        copystat(src, dst)
    except OSError as why:
        # can't copy file access times on 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 []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)

1.2. Пример rmtree

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

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, onerror=remove_readonly)

2. Операции архивирования

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

root_dir и base_dir по умолчанию равны текущему каталогу.

Если dry_run равно true, архив не создается, но операции, которые должны были быть выполнены, записываются в logger.

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

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

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

shutil.get_archive_formats()

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

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

• zip: ZIP-файл (если модуль zlib доступен).
• tar: нескомпрессированный tar-файл.
• 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()).

Если задано, 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.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: сжатый tar-файл (gzip) (если модуль zlib доступен).
• bztar: сжатый tar-файл (bzip2) (если модуль bz2 доступен).
• xztar: сжатый tar-файл (xz) (если модуль lzma доступен).

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

2.1. Пример архивирования

В этом примере мы создаем gzip'ed 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

3. Определение размера выходного терминала

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.