shutil — Файловые операции высокого уровня¶

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

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

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

shutil.copyfile(src, dst, *, follow_symlinks=True)¶

Скопировать содержимое (без метаданных) файла с именем src в файл с именем dst и вернуть dst наиболее эффективным способом. src и dst - это объекты типа path или имена путей, заданные в виде строк.

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

Место назначения должно быть доступно для записи; в противном случае будет вызвано исключение OSError. Если dst уже существует, он будет заменен. Специальные файлы, такие как символьные или блочные устройства и трубы, не могут быть скопированы с помощью этой функции.

Если follow_symlinks равно false и src является символической ссылкой, то вместо копирования файла, на который указывает src, будет создана новая символическая ссылка.

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

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

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

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы fast-copy. См. раздел Эффективные операции копирования в зависимости от платформы.

exception shutil.SameFileError¶

Это исключение возникает, если источник и пункт назначения в copyfile() являются одним и тем же файлом.

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

shutil.copymode(src, dst, *, follow_symlinks=True)¶

Скопируйте биты разрешения из src в dst. Содержимое файла, владелец и группа не затрагиваются. src и dst - это объекты типа path или имена путей, заданные в виде строк. Если follow_symlinks равно false, и src и dst являются символическими ссылками, copymode() попытается изменить режим самого dst (а не файла, на который он указывает). Эта функция доступна не на всех платформах; пожалуйста, обратитесь к copystat() за дополнительной информацией. Если copymode() не может модифицировать символические ссылки на локальной платформе, а его попросят это сделать, он ничего не сделает и вернется.

Вызывает auditing event shutil.copymode с аргументами src, dst.

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

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

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

Если 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.

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

Изменено в версии 3.3: Добавлен аргумент follow_symlinks и поддержка расширенных атрибутов Linux.

shutil.copy(src, dst, *, follow_symlinks=True)¶

Копирует файл src в файл или каталог dst. src и dst должны быть path-like objects или строками. Если dst указывает каталог, файл будет скопирован в dst с использованием базового имени файла из src. Если dst указывает уже существующий файл, он будет заменен. Возвращает путь к вновь созданному файлу.

Если follow_symlinks равно false, а src является символической ссылкой, dst будет создан как символическая ссылка. Если follow_symlinks равно true и src является символической ссылкой, dst будет копией файла, на который ссылается src.

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

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

Вызывает auditing event shutil.copymode с аргументами src, dst.

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

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы fast-copy. См. раздел Эффективные операции копирования в зависимости от платформы.

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

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

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

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

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

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

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

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы fast-copy. См. раздел Эффективные операции копирования в зависимости от платформы.

shutil.ignore_patterns(*patterns)¶

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

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

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

Если возникает исключение(я), то выдается сообщение Error со списком причин.

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

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

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

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

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

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы fast-copy. См. раздел Эффективные операции копирования в зависимости от платформы.

Добавлено в версии 3.8: Параметр dirs_exist_ok.

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

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

Примечание

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

Если указано onerror, то это должна быть вызываемая функция, принимающая три параметра: функция, путь и excinfo.

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

Вызывает auditing event 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 или как dst, а src будет удален.

Если указана copy_function, она должна быть вызываемой, принимающей два аргумента src и dst, и будет использоваться для копирования src в dst, если os.rename() не может быть использована. Если источником является каталог, вызывается copytree(), передавая ему copy_function(). Функцией copy_function по умолчанию является copy2(). Использование copy() в качестве функции копирования позволяет успешно выполнить перемещение, если невозможно скопировать метаданные, за счет отсутствия копирования метаданных.

Вызывает auditing event shutil.move с аргументами src, dst.

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

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

Изменено в версии 3.8: Для более эффективного копирования файла могут использоваться специфические для платформы системные вызовы fast-copy. См. раздел Эффективные операции копирования в зависимости от платформы.

Изменено в версии 3.9: Принимает path-like object как для src, так и для dst.

shutil.disk_usage(path)¶

Возвращает статистику использования диска по заданному пути в виде named tuple с атрибутами total, used и free, которые представляют собой объем общего, используемого и свободного пространства в байтах. path может быть файлом или каталогом.

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

Изменено в версии 3.8: В Windows path теперь может быть файлом или каталогом.

Availability: Unix, Windows.

shutil.chown(path, user=None, group=None)¶

Изменить владельца user и/или group данного пути.

user может быть именем пользователя системы или uid; то же самое относится к group. Требуется как минимум один аргумент.

См. также os.chown(), базовая функция.

Вызывает auditing event shutil.chown с аргументами path, user, group.

Availability: Unix.

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

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)¶

Возвращает путь к исполняемому файлу, который будет запущен при вызове заданного cmd. Если cmd не будет вызвано, возвращается None.

mode - это маска разрешения, передаваемая в os.access(), по умолчанию определяющая, существует ли файл и является ли он исполняемым.

Если путь не указан, используются результаты os.environ(), возвращающие либо значение «PATH», либо возврат os.defpath.

В Windows текущий каталог всегда добавляется к path, независимо от того, используете ли вы каталог по умолчанию или предоставляете свой собственный, что является поведением командной оболочки при поиске исполняемых файлов. Кроме того, при поиске cmd в пути проверяется переменная окружения 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 - имя создаваемого файла, включая путь, без расширения, специфичного для формата. формат - формат архива: один из «zip» (если доступен модуль zlib), «tar», «gztar» (если доступен модуль zlib), «bztar» (если доступен модуль bz2) или «xztar» (если доступен модуль lzma).

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

base_dir - это каталог, из которого мы начинаем архивирование; т.е. base_dir будет общим префиксом всех файлов и каталогов в архиве. base_dir должен быть указан относительно root_dir. Как использовать base_dir и root_dir вместе, смотрите в Пример архивирования с использованием base_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.

Примечание

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

Изменено в версии 3.8: Современный формат pax (POSIX.1-2001) теперь используется вместо устаревшего формата GNU для архивов, созданных с помощью format="tar".

Изменено в версии 3.10.6: Теперь эта функция стала потокобезопасной при создании стандартных архивов .zip и 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 - имя целевого каталога, в который распаковывается архив. Если имя не указано, используется текущий рабочий каталог.

формат - формат архива: один из «zip», «tar», «gztar», «bztar» или «xztar». Или любой другой формат, зарегистрированный с помощью register_unpack_format(). Если не указано, unpack_archive() будет использовать расширение имени файла архива и проверять, зарегистрирован ли распаковщик для этого расширения. Если таковой не найден, выдается сообщение ValueError.

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

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

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

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

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── 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.

См. также: Единая спецификация UNIX, версия 2, Other Environment Variables.

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