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

Вызывает событие аудита аудита shutil.copyfile с аргументами src, dst.

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

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

Изменено в версии 3.8: Внутренне могут использоваться платформенные системные вызовы быстрой копии для более эффективного копирования файла. См. раздел "Зависимые от платформы эффективные операции копирования".

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

Вызывает событие аудита аудита 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 ложно и 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: Внутренне могут использоваться платформенные системные вызовы быстрой копии для более эффективного копирования файла. См. раздел "Зависимые от платформы эффективные операции копирования".

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

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

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

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

Вызывает событие аудита shutil.copyfile с аргументами src, dst.

Вызывает событие аудита shutil.copystat с аргументами src, dst.

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

Изменено в версии 3.8: Возможно использование платформозависимых системных вызовов для быстрого копирования для более эффективного копирования файла. См. раздел «Платформозависимые эффективные операции копирования».

shutil.ignore_patterns(*patterns)

Эта функция-фабрика создает функцию, которая может использоваться в качестве вызываемого объекта для аргумента ignore copytree(), игнорируя файлы и каталоги, которые соответствуют одному из шаблонов 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 истинно, символические ссылки в исходном дереве представлены как символические ссылки в новом дереве, и метаданные исходных ссылок копируются по мере возможности платформы; если ложно или опущено, содержимое и метаданные связанных файлов копируются в новое дерево.

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

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

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

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

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

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

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

Изменено в версии 3.8: Возможно использование платформозависимых системных вызовов для быстрого копирования для более эффективного копирования файла. См. раздел «Платформозависимые эффективные операции копирования».

Новое в версии 3.8: Параметр dirs_exist_ok.

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

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

Примечание

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

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

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

Вызывает событие аудита shutil.rmtree с аргументом path.

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

Изменено в версии 3.8: В Windows больше не будет удалено содержимое каталога-соединения перед удалением соединения.

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 в 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: Внутренне могут использоваться платформенно-специфичные быстрые системные вызовы для более эффективного копирования файла. См. раздел Платформенно-зависимые эффективные операции копирования.

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

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, _):
    "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 — каталог, который будет корневым каталогом архива, все пути в архиве будут относительными к нему; например, обычно мы переходим в root_dir перед созданием архива.

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

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

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

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

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

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

Вызывает событие аудита auditing event 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 pax для новых архивов.
• 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.

Вызывает событие аудита auditing event shutil.unpack_archive с аргументами filename, extract_dir, format.

Изменено в версии 3.7: Принимает path-like object для 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

Получение размера терминала вывода

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.