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

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

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

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

Изменено в версии 3.3: Добавлен аргумент follow_symlinks.

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

Копирует биты разрешений, время последнего доступа, время последней модификации и флаги из src в dst. В Linux copystat() также копирует «расширенные атрибуты», где это возможно. Содержимое файла, владелец и группа не затрагиваются.

Если 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 или, если он опущен, они поднимают исключение.

Примечание

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

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

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

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

rmtree.avoids_symlink_attacks

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

Новое в версии 3.3.

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

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

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

Если место назначения находится в текущей файловой системе, то используется os.rename(). В противном случае src копируется в dst с использованием copy_function, а затем удаляется. В случае символических ссылок будет создана новая символическая ссылка, указывающая на целевой объект src в dst или как 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, представляющими объём общего, используемого и свободного пространства в байтах. В Windows path должен быть каталогом; в Unix он может быть файлом или каталогом.

Новое в версии 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).

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

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

11.10.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: сжатый 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.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().

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

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