shutil — High-level file operations — Python 3.13.1 documentation

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

等同于 copy() 除了 copy2() 还试图保留文件元数据。

当 follow_symlinks is false, and src is a symbolic link, copy2() attempts to copy all metadata from the src symbolic link to the newly created dst symbolic link. However, this functionality is not available on all platforms. On platforms where some or all of this functionality is unavailable, copy2() will preserve all the metadata it can; copy2() never raises an exception because it cannot preserve file metadata.

copy2() 使用 copystat() to copy the file metadata. Please see copystat() for more information about platform support for modifying symbolic link metadata.

引发审计事件 shutil.copyfile 采用自变量 src , dst .

引发审计事件 shutil.copystat 采用自变量 src , dst .

3.3 版改变：添加 follow_symlinks argument, try to copy extended file system attributes too (currently Linux only). Now returns path to the newly created file.

3.8 版改变： Platform-specific fast-copy syscalls may be used internally in order to copy the file more efficiently. See 从属平台的高效拷贝操作章节。

shutil. ignore_patterns ( * patterns ) ¶

This factory function creates a function that can be used as a callable for copytree() 's ignore argument, ignoring files and directories that match one of the glob-style patterns provided. See the example below.

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

Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory. All intermediate directories needed to contain dst will also be created by default.

Permissions and times of directories are copied with copystat() , individual files are copied using copy2() .

若 symlinks is true, symbolic links in the source tree are represented as symbolic links in the new tree and the metadata of the original links will be copied as far as the platform allows; if false or omitted, the contents and metadata of the linked files are copied to the new tree.

当 symlinks is false, if the file pointed to by the symlink doesn’t exist, an exception will be added in the list of errors raised in an Error exception at the end of the copy process. You can set the optional ignore_dangling_symlinks flag to true if you want to silence this exception. Notice that this option has no effect on platforms that don’t support os.symlink() .

若 ignore is given, it must be a callable that will receive as its arguments the directory being visited by copytree() , and a list of its contents, as returned by os.listdir() 。由于 copytree() is called recursively, the ignore callable will be called once for each directory that is copied. The callable must return a sequence of directory and file names relative to the current directory (i.e. a subset of the items in its second argument); these names will then be ignored in the copy process. ignore_patterns() can be used to create such a callable that ignores names based on glob-style patterns.

若发生异常， Error is raised with a list of reasons.

若 copy_function is given, it must be a callable that will be used to copy each file. It will be called with the source path and the destination path as arguments. By default, copy2() is used, but any function that supports the same signature (like copy() ) can be used.

若 dirs_exist_ok is false (the default) and dst already exists, a FileExistsError 被引发。若 dirs_exist_ok is true, the copying operation will continue if it encounters existing directories, and files within the dst tree will be overwritten by corresponding files from the src tree.

引发审计事件 shutil.copytree 采用自变量 src , dst .

3.2 版改变：添加 copy_function argument to be able to provide a custom copy function. Added the ignore_dangling_symlinks argument to silence dangling symlinks errors when symlinks 为 False。

3.3 版改变：拷贝元数据当 symlinks is false. Now returns dst .

3.8 版改变： Platform-specific fast-copy syscalls may be used internally in order to copy the file more efficiently. See 从属平台的高效拷贝操作章节。

3.8 版改变：添加 dirs_exist_ok 参数。

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

Delete an entire directory tree; path must point to a directory (but not a symbolic link to a directory). If ignore_errors is true, errors resulting from failed removals will be ignored; if false or omitted, such errors are handled by calling a handler specified by onexc or onerror or, if both are omitted, exceptions are propagated to the caller.

此函数可以支持相对于目录描述符的路径 .

注意

On platforms that support the necessary fd-based functions a symlink attack resistant version of rmtree() is used by default. On other platforms, the rmtree() implementation is susceptible to a symlink attack: given proper timing and circumstances, attackers can manipulate symlinks on the filesystem to delete files they wouldn’t be able to access otherwise. Applications can use the rmtree.avoids_symlink_attacks function attribute to determine which case applies.

若 onexc is provided, it must be a callable that accepts three parameters: function , path ，和 excinfo .

The first parameter, function , is the function which raised the exception; it depends on the platform and implementation. The second parameter, path , will be the path name passed to function . The third parameter, excinfo , is the exception that was raised. Exceptions raised by onexc will not be caught.

The deprecated onerror 类似于 onexc , except that the third parameter it receives is the tuple returned from sys.exc_info() .

引发审计事件 shutil.rmtree 采用自变量 path , dir_fd .

3.3 版改变： Added a symlink attack resistant version that is used automatically if platform supports fd-based functions.

3.8 版改变： On Windows, will no longer delete the contents of a directory junction before removing the junction.

3.11 版改变：添加 dir_fd 参数。

3.12 版改变：添加 onexc parameter, deprecated onerror .

Changed in version 3.13: rmtree() now ignores FileNotFoundError exceptions for all but the top-level path. Exceptions other than OSError and subclasses of OSError are now always propagated to the caller.

rmtree. avoids_symlink_attacks ¶

Indicates whether the current platform and implementation provides a symlink attack resistant version of rmtree() . Currently this is only true for platforms supporting fd-based directory access functions.

Added in version 3.3.

shutil. move ( src , dst , copy_function = copy2 ) ¶

Recursively move a file or directory ( src ) to another location and return the destination.

若 dst is an existing directory or a symlink to a directory, then src is moved inside that directory. The destination path in that directory must not already exist.

若 dst already exists but is not a directory, it may be overwritten depending on os.rename() 语义。

If the destination is on the current filesystem, then os.rename() is used. Otherwise, src is copied to the destination using copy_function and then removed. In case of symlinks, a new symlink pointing to the target of src will be created as the destination and src will be removed.

若 copy_function is given, it must be a callable that takes two arguments, src and the destination, and will be used to copy src to the destination if os.rename() cannot be used. If the source is a directory, copytree() is called, passing it the copy_function 。默认 copy_function is copy2() 。使用 copy() 作为 copy_function allows the move to succeed when it is not possible to also copy the metadata, at the expense of not copying any of the metadata.

引发审计事件 shutil.move 采用自变量 src , dst .

3.3 版改变： Added explicit symlink handling for foreign filesystems, thus adapting it to the behavior of GNU’s mv . Now returns dst .

3.5 版改变：添加 copy_function 关键词自变量。

3.8 版改变： Platform-specific fast-copy syscalls may be used internally in order to copy the file more efficiently. See 从属平台的高效拷贝操作章节。

3.9 版改变：接受像路径对象 for both src and dst .

shutil. disk_usage ( path ) ¶

Return disk usage statistics about the given path as a 命名元组 with the attributes total , used and free , which are the amount of total, used and free space, in bytes. path may be a file or a directory.

注意

On Unix filesystems, path must point to a path within a mounted filesystem partition. On those platforms, CPython doesn’t attempt to retrieve disk usage information from non-mounted filesystems.

Added in version 3.3.

3.8 版改变：在 Windows， path can now be a file or directory.

可用性：Unix、Windows。

shutil. chown ( path , user = None , group = None , * , dir_fd = None , follow_symlinks = True ) ¶

Change owner user and/or group 为给定 path .

user can be a system user name or a uid; the same applies to group . At least one argument is required.

另请参阅 os.chown() ，底层函数。

引发审计事件 shutil.chown 采用自变量 path , user , group .

可用性：Unix。

Added in version 3.3.

Changed in version 3.13: 添加 dir_fd and follow_symlinks 参数。

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

Return the path to an executable which would be run if the given cmd was called. If no cmd would be called, return None .

mode is a permission mask passed to os.access() , by default determining if the file exists and is executable.

path is a “ PATH string” specifying the directories to look in, delimited by os.pathsep 。当没有 path is specified, the PATH environment variable is read from os.environ , falling back to os.defpath if it is not set.

On Windows, the current directory is prepended to the path if mode does not include os.X_OK 。当 mode does include os.X_OK , the Windows API NeedCurrentDirectoryForExePathW will be consulted to determine if the current directory should be prepended to path . To avoid consulting the current working directory for executables: set the environment variable NoDefaultCurrentDirectoryInExePath .

Also on Windows, the PATHEXT environment variable is used to resolve commands that may not already include an extension. For example, if you call shutil.which("python") , which() will search PATHEXT to know that it should look for python.exe within the path directories. For example, on Windows:

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

This is also applied when cmd is a path that contains a directory component:

>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'

Added in version 3.3.

3.8 版改变： The bytes 类型现在接受。若 cmd 类型为 bytes ，结果类型也是 bytes .

3.12 版改变： On Windows, the current directory is no longer prepended to the search path if mode 包括 os.X_OK and WinAPI NeedCurrentDirectoryForExePathW(cmd) is false, else the current directory is prepended even if it is already in the search path; PATHEXT is used now even when cmd includes a directory component or ends with an extension that is in PATHEXT ; and filenames that have no extension can now be found.

exception shutil. Error ¶

This exception collects exceptions that are raised during a multi-file operation. For copytree() , the exception argument is a list of 3-tuples ( srcname , dstname , exception ).

`shutil` — 高级文件操作 ¶

目录和文件操作 ¶

从属平台的高效拷贝操作 ¶

copytree 范例 ¶

rmtree 范例 ¶

存档操作 ¶

存档范例 ¶

存档范例采用 base_dir ¶

查询输出终端的大小 ¶

内容表

上一话题

下一话题

本页

内容表

上一话题

下一话题

本页

shutil — 高级文件操作 ¶

目录和文件操作 ¶

从属平台的高效拷贝操作 ¶

copytree 范例 ¶

rmtree 范例 ¶

存档操作 ¶

存档范例 ¶

存档范例采用 base_dir ¶

查询输出终端的大小 ¶

内容表

上一话题

下一话题

本页

`shutil` — 高级文件操作 ¶