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

Если 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. Если dst указывает на файл, который уже существует, он будет перезаписан. Возвращает путь к новосозданному файлу.

Если 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(), игнорируя файлы и каталоги, которые соответствуют одному из предоставленных шаблонов patterns в стиле glob. См. пример ниже.

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

Рекурсивно копирует всю древовидную структуру каталогов, укорененную в src, в каталог с именем dst и возвращает целевой каталог. Все промежуточные каталоги, необходимые для содержать dst, также будут созданы по умолчанию.

Разрешения и временные метки каталогов копируются с помощью copystat(), отдельные файлы копируются с помощью copy2().

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

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

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

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

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

Если dirs_exist_ok ложно (по умолчанию), а dst уже существует, поднимается FileExistsError. Если dirs_exist_ok равно true, операция копирования будет продолжена, если она столкнется с существующими каталогами, и файлы в дереве dst будут перезаписаны соответствующими файлами из дерева src.

Вызывает событие аудита 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 равно True, ошибки, возникшие в результате неудаленных удалений, будут проигнорированы; если ложно или опущено, такие ошибки обрабатываются с помощью обработчика, указанного в onerror, или, если он опущен, они генерируют исключение.

Примечание

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

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

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

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

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

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

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

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

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

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

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

Изменено в версии 3.9: Принимает объект, подобный пути для src и dst.

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() аргумент исключения — список из трёх кортежей (srcname, dstname, exception).

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 не используется и устарел.

Вызывает событие аудита 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’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.

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

Предупреждение

Никогда не распаковывайте архивы из ненадежных источников без предварительного анализа. Возможно, файлы создаются за пределами пути, указанного в аргументе extract_dir, например, члены с абсолютными именами файлов, начинающимися с «/», или именами файлов с двумя точками «..».

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

>>> 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 Specification, версия 2, Другие переменные окружения.

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