shutil

源代码： lib / shutil.py

shutil模块提供了许多关于文件和文件集合的高级操作。特别提供了支持文件复制和删除的功能。有关单个文件的操作，另请参阅os模块。

警告

即使更高级别的文件复制功能（shutil.copy()，shutil.copy2()）也不能复制所有文件元数据。

在POSIX平台上，这意味着文件所有者和组以及ACL都会丢失。在Mac OS上，不使用资源分叉和其他元数据。这意味着资源将会丢失，文件类型和创建者代码将不正确。在Windows上，不会复制文件所有者，ACL和备用数据流。

1.目录和文件操作

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

在类文件对象的内容复制金管会的文件对象fdst。整数长度（如果给出）是缓冲区大小。具体而言，负长度值意味着复制数据，而不会以块的形式循环源数据; 默认情况下，数据以块读取，以避免不受控制的内存消耗。请注意，如果fsrc对象的当前文件位置不为0，则只会复制当前文件位置到文件末尾的内容。

shutil.copyfile(src, dst)

将名为src的文件的内容（无元数据）复制到名为dst的文件中。dst必须是完整的目标文件名; 查看shutil.copy()接受目标目录路径的副本。如果src和dst是相同的文件，Error则引发。目标位置必须可写; 否则IOError会引发异常。如果dst已经存在，它将被替换。特殊文件如字符或块设备和管道不能使用此功能进行复制。src和dst是以字符串形式给出的路径名。

shutil.copymode(src, dst)

将权限位从src复制到dst。文件内容，所有者和组不受影响。src和dst是以字符串形式给出的路径名。

shutil.copystat(src, dst)

将权限位，上次访问时间，上次修改时间以及src中的标志复制到dst。文件内容，所有者和组不受影响。src和dst是以字符串形式给出的路径名。

shutil.copy(src, dst)

将文件src复制到文件或目录dst。如果dst是目录，则在指定的目录中创建（或覆盖）与src具有相同基本名称的文件。权限位被复制。src和dst是以字符串形式给出的路径名。

shutil.copy2(src, dst)

与之类似shutil.copy()，但元数据也被复制 - 实际上，这只是shutil.copy()紧跟其后copystat()。这与Unix命令cp -p类似。

shutil.ignore_patterns(*patterns)

这个工厂函数创建一个可以作为一个可调用一个函数copytree()的忽略说法，忽略匹配通配符式样的一个文件和目录的方式提供。看下面的例子。

2.6版本中的新功能。

shutil.copytree(src, dst, symlinks=False, ignore=None)

递归复制以src为根的整个目录树。由dst命名的目标目录不能存在; 它将被创建以及丢失的父目录。权限和目录的时间被复制copystat()，个别文件被复制使用shutil.copy2()。

如果符号链接为真，则源树中的符号链接在新树中表示为符号链接，但不会复制原始链接的元数据; 如果为false或省略，链接文件的内容和元数据将被复制到新树中。

如果给出了忽略，它必须是一个可调用的函数，它将接收作为其参数的被访问目录copytree()，以及其返回的内容列表os.listdir()。由于copytree()被递归调用，所以被复制的每个目录都会调用一次忽略调用。可调用函数必须返回一系列相对于当前目录的目录和文件名称（即第二个参数中的项目子集）; 这些名称将在复制过程中被忽略。ignore_patterns()可用于创建可忽略基于全局样式模式的名称的可调用对象。

如果发生异常，Error则列出一个理由列表。

源代码应该被视为一个例子而不是最终的工具。

Error如果在复制过程中发生任何异常，而不是打印消息，则会引发版本2.3中的更改。

在版本2.5中更改：创建创建dst所需的中间目录，而不是引发错误。复制使用目录的权限和时间copystat()。

在版本2.6中进行了更改：添加了忽略参数，以便能够影响正在复制的内容。

shutil.rmtree(path[, ignore_errors[, onerror]])

删除整个目录树；路径必须指向一个目录（但不是指向目录的符号链接）。如果ignore_errors为true，那么由失败的清除导致的错误将被忽略; 如果为false或省略，则通过调用由onerror指定的处理程序来处理此类错误，或者如果省略，则会引发异常。

如果提供了onerror，它必须是可接受的，它接受三个参数：函数，路径和excinfo。第一个参数函数是引发异常的函数; 这将是os.path.islink()，os.listdir()，os.remove()或os.rmdir()。第二个参数path将是传递给函数的路径名。第三个参数excinfo将是返回的异常信息sys.exc_info()。通过抛出的异常的onerror不会被抓住。

在版本2.6中进行了更改：明确检查路径是符号链接，并OSError在此情况下进行提升。

shutil.move(src, dst)

递归地将文件或目录（src）移动到另一个位置（dst）。

如果目的地是一个现有的目录，那么src会在该目录内移动。如果目标已经存在但不是目录，则可能会根据os.rename()语义覆盖目标。

如果目标位于当前文件系统上，则会os.rename()被使用。否则，将src复制（使用shutil.copy2()）到dst然后删除。

2.3版本的新功能。

exception shutil.Error

此异常收集多文件操作期间引发的异常。因为copytree()，异常参数是一个3元组列表（srcname，dstname，exception）。

2.3版本的新功能。

1.1. copytree示例

这个例子是copytree()上面描述的函数的实现，省略了docstring。它演示了该模块提供的许多其他功能。

def copytree(src, dst, symlinks=False, ignore=None):
    names = os.listdir(src)
    if ignore is not None:
        ignored_names = ignore(src, names)
    else:
        ignored_names = set()

    os.makedirs(dst)
    errors = []
    for name in names:
        if name in ignored_names:
            continue
        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, ignore)
            else:
                copy2(srcname, dstname)
            # XXX What about devices, sockets etc.?
        except (IOError, os.error) 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 WindowsError:
        # can't copy file access times on Windows
        pass
    except OSError as why:
        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)

2.归档操作

还提供了创建和读取压缩和存档文件的高级实用程序。他们依靠zipfile和tarfile模块。

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

创建一个存档文件（例如zip或tar）并返回其名称。

base_name是要创建的文件的名称，包括路径，减去任何格式特定的扩展名。格式是归档格式：“zip”（如果zlib模块或外部zip可执行文件可用），“tar”，“gztar”（如果zlib模块可用）或“bztar”（如果bz2模块可用）之一。

root_dir是一个将成为存档根目录的目录；即。我们通常在创建存档之前先chdir到root_dir。

base_dir是我们开始归档的目录；即。base_dir将是存档中所有文件和目录的通用前缀。

root_dir和base_dir都默认为当前目录。

所有者和组在创建tar归档时使用。默认情况下，使用当前所有者和组。

记录器必须是与PEP 282兼容的对象，通常是一个实例logging.Logger。

2.7版本的新功能。

shutil.get_archive_formats()

返回支持格式的列表进行存档。返回序列的每个元素都是一个元组(name, description)。

默认情况下shutil提供这些格式：

• zip：ZIP文件（如果zlib模块或外部zip可执行文件可用）。

• tar：解压缩的tar文件。

• gztar：gzip'ed tar文件（如果zlib模块可用）。

• bztar：bzip2'ed tar文件（如果bz2模块可用）。

您可以通过使用注册新格式或为任何现有格式提供您自己的归档程序register_archive_format()。

2.7版本的新功能。

shutil.register_archive_format(name, function[, extra_args[, description]])

注册归档程序以获取格式名称。函数是可调用的，将用于调用存档器。

如果给定，则extra_args是一个(name, value)将用作额外关键字参数的序列，当使用归档器可调用时。

描述用于get_archive_formats()返回归档器列表。默认为空列表。

2.7版本的新功能。

shutil.unregister_archive_format(name)

从支持的格式列表中删除存档格式名称。

2.7版本的新功能。

2.1. 存档示例

在这个例子中，我们创建一个包含.ssh用户目录中所有文件的gzip'ed tar文件存档：

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