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

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

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

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

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

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

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

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

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

copy() копирует данные файла и режим разрешений файла (см. os.chmod()). Другие метаданные, такие как время создания и модификации файла, не сохраняются. Для сохранения всех метаданных исходного файла используйте copy2().

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

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

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

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

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

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

shutil.ignore_patterns(*patterns)

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

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: Добавлена явная обработка символических ссылок для внешних файловых систем, таким образом адаптирующая её к поведению mv GNU. Теперь возвращает 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).

Пример 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)

Пример 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)

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

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

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

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

• zip: ZIP-архив (если модуль zlib доступен).
• tar: нескомпрессированный tar-архив.
• gztar: gzip’ed tar-архив (если модуль zlib доступен).
• bztar: bzip2’ed tar-архив (если модуль bz2 доступен).
• xztar: xz’ed 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.

Изменено в версии 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’ed tar-архив (если модуль zlib доступен).
• bztar: bzip2’ed tar-архив (если модуль bz2 доступен).
• xztar: xz’ed tar-архив (если модуль lzma доступен).

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

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

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

Пример архивирования с 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.

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

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