一图看懂 shutil 模块：用于复制和归档文件和目录树, 资料整理+笔记（大全）

本文由 大侠(AhcaoZhu)原创，转载请声明。
链接: https://blog.csdn.net/Ahcao2008

摘要

全文介绍系统内置 shutil 模块、函数、类及类的方法和属性。
它通过代码抓取并经AI智能翻译和人工校对。
是一部不可多得的权威字典类工具书。它是系列集的一部分。后续陆续发布、敬请关注。【原创：AhcaoZhu大侠】

模块图

shutil
	◆os
	◆sys
	◆stat
	◆fnmatch
	◆collections
	◆errno
	◆nt

类关系图

◆object
	◆BaseException
		◆Exception
			◆OSError
				shutil.Error
					shutil.SameFileError
				shutil.ExecError
				shutil.ReadError
				shutil.SpecialFileError
			shutil.RegistryError
	◆tuple
		shutil.usage

模块全展开

【shutil】

shutil, fullname=shutil, file=shutil.py

用于复制和归档文件和目录树的实用程序函数。
XXX 这里的函数不会复制Mac上的资源fork或其他元数据。

统计

序号	类别	数量
2	bool	4
4	str	5
6	list	1
8	dict	3
9	module	7
10	class	7
11	function	37
13	residual	4
14	system	9
15	private	22
16	all	68

常量

bool

1 _ZLIB_SUPPORTED True
2 _BZ2_SUPPORTED True
3 _LZMA_SUPPORTED True
4 _use_fd_functions False

dict

5 _ARCHIVE_FORMATS {‘tar’: (<function _make_tarball at 0x0000000002F403A8>, [(‘compress’, None)], ‘uncompressed tar file’), ‘gztar’: (<func…
6 _UNPACK_FORMATS {‘tar’: ([‘.tar’], <function _unpack_tarfile at 0x0000000002F40A68>, [], ‘uncompressed tar file’), ‘zip’: ([‘.zip’], <fu…

模块

7 os

os, fullname=os, file=os.py

8 sys

sys, fullname=sys"

9 stat

stat, fullname=stat, file=stat.py

10 fnmatch

fnmatch, fullname=fnmatch, file=fnmatch.py

11 collections

collections, fullname=collections, file=collections_init_.py

12 errno

errno, fullname=errno"

13 nt

nt, fullname=nt"

函数

14 copyfileobj(fsrc, fdst, length=16384)

copyfileobj(fsrc, fdst, length=16384), module=shutil, line:76 at shutil.py

将数据从类文件对象fsrc(源)复制到类文件对象fdst（目的）

15 _samefile(src, dst)

_samefile(src, dst), module=shutil, line:84 at shutil.py

16 copyfile(src, dst, *, follow_symlinks=True)

copyfile(src, dst, *, follow_symlinks=True), module=shutil, line:96 at shutil.py

将数据从src复制到dst。
如果没有设置follow_symlinks并且src是一个符号链接，则new
将创建symlink，而不是复制它所指向的文件。

17 copymode(src, dst, *, follow_symlinks=True)

copymode(src, dst, *, follow_symlinks=True), module=shutil, line:125 at shutil.py

将模式位从src复制到dst。
如果没有设置follow_symlinks，当且仅当'src'和'dst'都是符号链接时，符号链接不会被跟随。
如果'lchmod'不可用(例如Linux)，这个方法什么都不做。

18 _copyxattr(*args, **kwargs)

_copyxattr(*args, **kwargs), module=shutil, line:171 at shutil.py

19 copystat(src, dst, *, follow_symlinks=True)

copystat(src, dst, *, follow_symlinks=True), module=shutil, line:174 at shutil.py

复制文件元数据。
将权限位、最后访问时间、最后修改时间和标志从'src'复制到'dst'。
在Linux上，copyystat()还在可能的地方复制“扩展属性”。文件内容、所有者和组不受影响。
'src'和'dst'是以字符串形式给出的路径名。
如果未设置可选标志'follow_symlinks'，当且仅当'src'和'dst'都是符号链接时，符号链接不会被遵循。

20 copy(src, dst, *, follow_symlinks=True)

copy(src, dst, *, follow_symlinks=True), module=shutil, line:234 at shutil.py

复制数据和模式位("cp src dst")。返回文件的目的地。
目标可以是一个目录。如果follow_symlinks为false，则symlinks将不会被跟踪。
这类似于GNU的“cp -P src dst”。
如果源文件和目标文件是同一个文件，则会引发SameFileError异常。

21 copy2(src, dst, *, follow_symlinks=True)

copy2(src, dst, *, follow_symlinks=True), module=shutil, line:252 at shutil.py

复制数据和元数据。返回文件的目的地。
使用copystat()复制元数据。请参阅copyystat函数获取更多信息。
目标可以是一个目录。
如果follow_symlinks为false, symlinks将不会被跟随。这类似GNU的“cp -P src dst”。

22 ignore_patterns(*patterns)

ignore_patterns(*patterns), module=shutil, line:270 at shutil.py

模式是一组用于排除文件的全局样式模式
可以用作copytree()忽略参数的函数。
Patterns是一组全局样式的模式用来排除文件的

23 copytree(src, dst, symlinks=False, ignore=None, copy_function=<function copy2 at 0x0000000002F3AD38>, ignore_dangling_symlinks=False)

copytree(src, dst, symlinks=False, ignore=None, copy_function=<function copy2 at 0x0000000002F3AD38>, ignore_dangling_symlinks=False), module=shutil, line:282 at shutil.py

递归复制目录树。
目标目录必须不存在。如果发生异常，将引发一个Error，并给出原因列表。
如果可选符号链接标志为true，则源树中的符号链接将导致目标树中的符号链接;如果为false，则复制由符号链接指向的文件的内容。
如果符号链接指向的文件不存在，则会在复制过程结束时Error异常引发的错误列表中添加异常。
如果你想关闭这个异常，你可以将可选的忽略悬挂符号链接标志设置为true。注意，这对不支持os.symlink的平台没有影响。
可选的ignore参数是一个可调用参数。如果给定，则使用'src'形参调用它，这是copytree()正在访问的目录，'names'是'src'内容列表，由os.listdir()返回:
由于copytree()是递归调用的，因此对于复制的每个目录，callable将被调用一次。它返回一个相对于不应该复制的'src'目录的名称列表。
可选的copy函数参数是一个可调用函数，用于复制每个文件。它将以源路径和目标路径作为参数调用。
默认情况下，使用copy2()，但可以使用任何支持相同签名的函数(如copy())。

24 _rmtree_unsafe(path, onerror)

_rmtree_unsafe(path, onerror), module=shutil, line:372 at shutil.py

25 _rmtree_safe_fd(topfd, path, onerror)

_rmtree_safe_fd(topfd, path, onerror), module=shutil, line:407 at shutil.py

26 rmtree(path, ignore_errors=False, οnerrοr=None)

rmtree(path, ignore_errors=False, οnerrοr=None), module=shutil, line:459 at shutil.py

递归删除目录树。
如果设置了ignore_errors，则错误将被忽略;否则，如果设置了onerror，则调用它来处理带有参数(func, path, exc info)的错误，
其中func依赖于平台和实现;Path是导致该函数失败的参数;exc_info是一个由sys.exc_info()返回的信息。
如果ignore_errors为false且onerror为None，则会引发异常。

27 _basename(path)

_basename(path), module=shutil, line:522 at shutil.py

28 move(src, dst, copy_function=<function copy2 at 0x0000000002F3AD38>)

move(src, dst, copy_function=<function copy2 at 0x0000000002F3AD38>), module=shutil, line:528 at shutil.py

递归地将文件或目录移动到另一个位置。这类似于Unix的"mv"命令。返回文件或目录的目标。
如果目标是目录或指向目录的符号链接，则源文件将移动到该目录内。目标路径不能已经存在。
如果目标已经存在但不是目录，则可能会根据os.rename()语义将其覆盖。如果目标在当前文件系统上，则使用rename()。
否则，src将被复制到目标，然后删除。如果os.rename()因为跨文件系统重命名而失败，符号链接将在新名称下重新创建。
可选的'copy function'参数是一个可调用对象，用于复制源文件或委托给'copytree'。
默认情况下，使用copy2()，但可以使用任何支持相同签名的函数(如copy())。
这里还有很多事情可以做……看一看mvc，就会发现这个实现掩盖了很多问题。

29 _destinsrc(src, dst)

_destinsrc(src, dst), module=shutil, line:584 at shutil.py

30 _get_gid(name)

_get_gid(name), module=shutil, line:593 at shutil.py

返回给定组名的gid。

31 _get_uid(name)

_get_uid(name), module=shutil, line:605 at shutil.py

返回给定用户名的uid。

32 _make_tarball(base_name, base_dir, compress=‘gzip’, verbose=0, dry_run=0, owner=None, group=None, logger=None)

_make_tarball(base_name, base_dir, compress=‘gzip’, verbose=0, dry_run=0, owner=None, group=None, logger=None), module=shutil, line:617 at shutil.py

从'base_dir'下的所有文件中创建一个(可能是压缩的)tar文件。
'compress'必须为"gzip"(默认值)，"bzip2"， "xz"，或None。
'owner'和'group'可用于为正在构建的存档定义所有者和组。
如果未提供，则将使用当前所有者和组。
输出的tar文件将被命名为“base_name”+“.tar”，可能还要加上适当的压缩扩展名(“.gz”，“.tar”) .Bz2 "，或".xz")。返回输出文件名。

33 _make_zipfile(base_name, base_dir, verbose=0, dry_run=0, logger=None)

_make_zipfile(base_name, base_dir, verbose=0, dry_run=0, logger=None), module=shutil, line:682 at shutil.py

从'base_dir'下的所有文件中创建一个zip文件。
输出的zip文件将被命名为'base_name' + ".zip"。返回输出zip文件的名称。

34 get_archive_formats()

get_archive_formats(), module=shutil, line:743 at shutil.py

返回归档和解归档所支持的格式的列表。
返回序列的每个元素都是一个元组(name, description)

35 register_archive_format(name, function, extra_args=None, description=‘’)

register_archive_format(name, function, extra_args=None, description=‘’), module=shutil, line:753 at shutil.py

注册存档格式。
“Name”是格式的名称。函数是用于创建存档的可调用对象。
如果提供，额外的args是(名称，值)元组序列，将作为参数传递给可调用对象。
Description可以用来描述格式，并将由get_archive_formats()函数返回。

36 unregister_archive_format(name)

unregister_archive_format(name), module=shutil, line:774 at shutil.py

37 make_archive(base_name, format, root_dir=None, base_dir=None, verbose=0, dry_run=0, owner=None, group=None, logger=None)

make_archive(base_name, format, root_dir=None, base_dir=None, verbose=0, dry_run=0, owner=None, group=None, logger=None), module=shutil, line:777 at shutil.py

创建一个存档文件(例如:Zip or tar)。
'base name'是要创建的文件名称，减去任何特定于格式的扩展名;
'format'是存档格式:"zip"， "tar"， "gztar"， "bztar"，或"xztar"之一。或任何其他注册格式。
'root_dir'是一个目录，将是存档的根目录;ie。在创建存档之前，我们通常将chdir设置为“根目录”。'base_dir'是我们开始存档的目录;
即，'base_dir'将是存档中所有文件和目录的公共前缀。
'root_dir'和'base_dir'都默认为当前目录。返回存档文件的名称。
'owner'和'group'在创建tar存档时使用。默认情况下，使用当前所有者和组。

38 get_unpack_formats()

get_unpack_formats(), module=shutil, line:832 at shutil.py

返回用于解包的支持格式的列表。
返回序列的每个元素都是一个元组(名称、扩展名、描述)。
(name, extensions, description)

39 _check_unpack_options(extensions, function, extra_args)

_check_unpack_options(extensions, function, extra_args), module=shutil, line:843 at shutil.py

检查什么被注册为unpacker。

40 register_unpack_format(name, extensions, function, extra_args=None, description=‘’)

register_unpack_format(name, extensions, function, extra_args=None, description=‘’), module=shutil, line:861 at shutil.py

注册解包格式。
'name'是格式的名称。'extensions'是与格式相对应的扩展名列表。
'function'是用于解包档案的可调用对象。可调用对象将接收要解包的存档。
如果它无法处理存档，则需要引发ReadError异常。如果提供，'extra_args'是(name, value)元组序列，将作为参数传递给可调用对象。
可以提供Description来描述格式，并将由get unpack formats()函数返回。

41 unregister_unpack_format(name)

unregister_unpack_format(name), module=shutil, line:883 at shutil.py

从注册表中删除包格式。

42 _ensure_directory(path)

_ensure_directory(path), module=shutil, line:887 at shutil.py

确保“path”的父目录存在

43 _unpack_zipfile(filename, extract_dir)

_unpack_zipfile(filename, extract_dir), module=shutil, line:893 at shutil.py

解压zip 'filename'到'extract_dir'

44 _unpack_tarfile(filename, extract_dir)

_unpack_tarfile(filename, extract_dir), module=shutil, line:927 at shutil.py

解压 tar/tar.gz/tar.bz2/tar.xz 'filename'到'extract_dir'

45 _find_unpack_format(filename)

_find_unpack_format(filename), module=shutil, line:958 at shutil.py

46 unpack_archive(filename, extract_dir=None, format=None)

unpack_archive(filename, extract_dir=None, format=None), module=shutil, line:965 at shutil.py

解压缩归档文件。
'filename'是存档的名称。
'extract_dir'是目标目录的名称，归档文件将在其中解压缩。
如果没有提供，则使用当前工作目录。
'format'是存档格式:"zip"， "tar"， "gztar"， "bztar"，或"xztar"之一。或任何其他注册格式。
如果没有提供，解包存档将使用文件名扩展名，并查看是否为该扩展名注册了解包程序。如果没有找到，则引发ValueError。

47 disk_usage(path)

disk_usage(path), module=shutil, line:1031 at shutil.py

返回关于给定路径的磁盘使用统计信息。
返回值是一个命名元组，属性为'total'， 'used'和'free'，它们是总空间，已使用空间和空闲空间的数量，以字节为单位。

48 chown(path, user=None, group=None)

chown(path, user=None, group=None), module=shutil, line:1042 at shutil.py

更改给定路径的所有者用户和组。
User和group可以是uid/gid或用户/组名，在这种情况下，它们将被转换为各自的uid/gid。

49 get_terminal_size(fallback=(80, 24))

get_terminal_size(fallback=(80, 24)), module=shutil, line:1073 at shutil.py

获取终端窗口的大小。
对于这两个维度中的每一个，环境变量COLUMNS和LINES分别被选中。如果变量已定义并且取值为正整数，实际使用。
当COLUMNS或LINES未定义时(这是常见情况)，系统连接的终端。sys.__stdout__被查询通过调用os.get_terminal_size。
如果由于系统不支持查询，或者由于我们没有连接到终端，无法成功查询终端大小，则使用fallback parameter中给出的值。
回退默认为(80,24)，这是许多终端仿真器使用的默认大小。返回值为os类型的命名元组。终端的大小。

50 which(cmd, mode=1, path=None)

which(cmd, mode=1, path=None), module=shutil, line:1118 at shutil.py

给定一个命令、模式和一个PATH字符串，返回PATH上符合给定模式的路径，如果没有这样的文件，则返回None。
'mode'默认为os.F_OK| os.X_OK。'path'默认为os.environment.get("PATH")的结果，或者可以用自定义搜索路径覆盖。

类

51 shutil.Error

Error, shutil.Error, module=shutil, line:0 at

52 shutil.SameFileError

SameFileError, shutil.SameFileError, module=shutil, line:0 at

当源文件和目标文件相同时将引发。

53 shutil.SpecialFileError

SpecialFileError, shutil.SpecialFileError, module=shutil, line:0 at

当试图执行一种特殊文件(例如命名管道)不支持的操作(例如复制)时被引发

54 shutil.ExecError

ExecError, shutil.ExecError, module=shutil, line:0 at

当命令无法执行时将被引发

55 shutil.ReadError

ReadError, shutil.ReadError, module=shutil, line:0 at

当存档无法读取时将被引发

56 shutil.RegistryError

RegistryError, shutil.RegistryError, module=shutil, line:0 at

当使用注册表存档和解包注册表的注册表操作失败时引发

57 shutil.usage

usage, shutil.usage, module=shutil, line:0 at

使用率(总数，已使用，免费)
usage(total, used, free)

property

1 free=<property object at 0x0000000002F3FC78> kind:property type:property class:<class ‘shutil.usage’>
2 total=<property object at 0x0000000002F3FBD8> kind:property type:property class:<class ‘shutil.usage’>
3 used=<property object at 0x0000000002F3FC28> kind:property type:property class:<class ‘shutil.usage’>

私有或局部

58 _ZLIB_SUPPORTED True
59 _BZ2_SUPPORTED True
60 _LZMA_SUPPORTED True
61 _samefile <function _samefile at 0x0000000002F36F78>
62 _copyxattr <function _copyxattr at 0x0000000002F3AB88>
63 _rmtree_unsafe <function _rmtree_unsafe at 0x0000000002F3AEE8>
64 _rmtree_safe_fd <function _rmtree_safe_fd at 0x0000000002F3AF78>
65 _use_fd_functions False
66 _basename <function _basename at 0x0000000002F400D8>
67 _destinsrc <function _destinsrc at 0x0000000002F401F8>
68 _get_gid <function _get_gid at 0x0000000002F40288>
69 _get_uid <function _get_uid at 0x0000000002F40318>
70 _make_tarball <function _make_tarball at 0x0000000002F403A8>
71 _make_zipfile <function _make_zipfile at 0x0000000002F40438>
72 _ARCHIVE_FORMATS {‘tar’: (<function _make_tarball at 0x0000000002F403A8>, [(‘compress’, None)], ‘uncompressed tar file’), ‘gztar’: (<func…
73 _check_unpack_options <function _check_unpack_options at 0x0000000002F40798>
74 _ensure_directory <function _ensure_directory at 0x0000000002F40948>
75 _unpack_zipfile <function _unpack_zipfile at 0x0000000002F409D8>
76 _unpack_tarfile <function _unpack_tarfile at 0x0000000002F40A68>
77 _UNPACK_FORMATS {‘tar’: ([‘.tar’], <function _unpack_tarfile at 0x0000000002F40A68>, [], ‘uncompressed tar file’), ‘zip’: ([‘.zip’], <fu…
78 _find_unpack_format <function _find_unpack_format at 0x0000000002F40AF8>
79 _ntuple_diskusage <class ‘shutil.usage’>

剩余

80 loader <_frozen_importlib_external.SourceFileLoader object at 0x0000000002EDF488>
81 spec ModuleSpec(name=‘shutil’, loader=<_frozen_importlib_external.SourceFileLoader object at 0x0000000002EDF488>, origin=‘…\lib\shutil.py’)
82 getpwnam None
83 getgrnam None

【os】

os, fullname=os, file=os.py

【sys】

sys, fullname=sys"

【stat】

stat, fullname=stat, file=stat.py

【fnmatch】

fnmatch, fullname=fnmatch, file=fnmatch.py

【collections】

collections, fullname=collections, file=collections_init_.py

【errno】

errno, fullname=errno"

【nt】

nt, fullname=nt"