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

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

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

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

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

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

shutil.copyfile(src, dst)

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

shutil.copymode(src, dst)

Копирует биты разрешений из src в dst. Содержимое, владелец и группа файла не затрагиваются. src и dst — имена путей, заданные в виде строк.

shutil.copystat(src, dst)

Копирует биты разрешений, время последнего доступа, время последней модификации и флаги из src в dst. Содержимое, владелец и группа файла не затрагиваются. src и dst — имена путей, заданные в виде строк.

shutil.copy(src, dst)

Копирует файл src в файл или каталог dst. Если dst — каталог, создаётся (или перезаписывается) файл с тем же именем, что и src, в указанном каталоге. Копируются биты разрешений. src и dst — имена путей, заданные в виде строк.

shutil.copy2(src, dst)

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

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

shutil.ignore_patterns(*patterns)

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

Новая функция в версии 2.6.

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

Рекурсивно копирует всю древовидную структуру каталогов, укоренённую в src. Каталог назначения, названный dst, не должен уже существовать; он будет создан, а также недостающие родительские каталоги. Разрешения и время каталогов копируются с помощью copystat(), отдельные файлы копируются с помощью shutil.copy2().

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

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

Если возникнут исключения, возбуждается исключение Error со списком причин.

Исходный код следует рассматривать как пример, а не как окончательный инструмент.

Изменено в версии 2.3: Исключение Error возбуждается, если возникают какие-либо исключения во время копирования, а не выводится сообщение.

Изменено в версии 2.5: Создаются промежуточные каталоги, необходимые для создания dst, вместо того, чтобы генерировать ошибку. Копируются разрешения и время каталогов с помощью copystat().

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

shutil.rmtree(path[, ignore_errors[, onerror]])

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

Если задан onerror, он должен быть вызываемым объектом, принимающим три параметра: function, path и excinfo. Первый параметр, function, — функция, которая возбудила исключение; он будет os.path.islink(), os.listdir(), os.remove() или os.rmdir(). Второй параметр, path, будет именем пути, переданным в function. Третий параметр, excinfo, будет информацией об исключении, возвращаемой функцией sys.exc_info(). Исключения, возбуждаемые onerror, не будут перехватываться.

Изменено в версии 2.6: Явно проверяется, является ли path символической ссылкой, и в этом случае возбуждается исключение OSError.

shutil.move(src, dst)

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

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

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

Новая функция в версии 2.3.

exception shutil.Error

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

Новая функция в версии 2.3.

1.1. Пример copytree

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

def copytree(src, dst, symlinks=False, ignore=None):
    names = os.listdir(src)
    if ignore is not None:
        ignored_names = ignore(src, names)
    else:
        ignored_names = set()

    os.makedirs(dst)
    errors = []
    for name in names:
        if name in ignored_names:
            continue
        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, ignore)
            else:
                copy2(srcname, dstname)
            # XXX What about devices, sockets etc.?
        except (IOError, os.error) 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 WindowsError:
        # can't copy file access times on Windows
        pass
    except OSError as why:
        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)

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 или внешняя zip программа), “tar”, “gztar” (если доступен модуль zlib), или “bztar” (если доступен модуль bz2).

root_dir — каталог, который будет корневым каталогом архива; то есть, обычно мы переходим в root_dir перед созданием архива.

base_dir — каталог, с которого мы начинаем архивирование; то есть, base_dir будет общим префиксом всех файлов и каталогов в архиве.

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

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

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

Введено в версии 2.7.

shutil.get_archive_formats()

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

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

• zip: ZIP-файл (если доступен модуль zlib или внешняя zip программа).
• tar: не сжатый файл tar.
• gztar: сжатый gzip файл tar (если доступен модуль zlib).
• bztar: сжатый bzip2 файл tar (если доступен модуль bz2).

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

Введено в версии 2.7.

shutil.register_archive_format(name, function[, extra_args[, description]])

Регистрирует архиватор для формата name. function — вызываемый объект, который будет использоваться для вызова архиватора.

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

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

Введено в версии 2.7.

shutil.unregister_archive_format(name)

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

Введено в версии 2.7.

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

В этом примере мы создаём сжатый 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