From a867ed553e3c459dadf3e393490cfa587177ea07 Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Fri, 21 Sep 2012 10:12:14 -0700 Subject: [PATCH] Cleanup/rewrite shutil docs regarding follow_symlinks and copying attributes. --- Doc/library/shutil.rst | 115 ++++++++++++++++++++++++++++++----------- 1 file changed, 84 insertions(+), 31 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 8ed7e9edb1c..080c9233a9a 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -50,14 +50,15 @@ Directory and files operations .. function:: copyfile(src, dst, *, follow_symlinks=True) Copy the contents (no metadata) of the file named *src* to a file named - *dst* and return *dst*. *dst* must be the complete target file name; look at - :func:`shutil.copy` for a copy that accepts a target directory path. If - *src* and *dst* are the same files, :exc:`Error` is raised. + *dst* and return *dst*. *src* and *dst* are path names given as strings. + *dst* must be the complete target file name; look at :func:`shutil.copy` + for a copy that accepts a target directory path. If *src* and *dst* + specify the same file, :exc:`Error` is raised. - The destination location must be writable; otherwise, an :exc:`OSError` exception - will be raised. If *dst* already exists, it will be replaced. Special files - such as character or block devices and pipes cannot be copied with this - function. *src* and *dst* are path names given as strings. + The destination location must be writable; otherwise, an :exc:`OSError` + exception will be raised. If *dst* already exists, it will be replaced. + Special files such as character or block devices and pipes cannot be + copied with this function. If *follow_symlinks* is false and *src* is a symbolic link, a new symbolic link will be created instead of copying the @@ -71,52 +72,104 @@ Directory and files operations .. function:: copymode(src, dst, *, follow_symlinks=True) Copy the permission bits from *src* to *dst*. The file contents, owner, and - group are unaffected. *src* and *dst* are path names given as strings. If - *follow_symlinks* is false, *src* is a symbolic link, and the operating - system supports modes for symbolic links (for example BSD-based ones), - the mode of the link will be copied. + group are unaffected. *src* and *dst* are path names given as strings. + If *follow_symlinks* is false, and both *src* and *dst* are symbolic links, + :func:`copymode` will attempt to modify the mode of *dst* itself (rather + than the file it points to). This functionality is not available on every + platform; please see :func:`copystat` for more information. If + :func:`copymode` cannot modify symbolic links on the local platform, and it + is asked to do so, it will do nothing and return. .. versionchanged:: 3.3 Added *follow_symlinks* argument. .. function:: copystat(src, dst, *, follow_symlinks=True) - Copy the permission bits, last access time, last modification time, and flags - from *src* to *dst*. The file contents, owner, and group are unaffected. *src* - and *dst* are path names given as strings. If *follow_symlinks* is false, and - *src* and *dst* are both symbolic links, the stats of the link will be copied as - far as the platform allows. On Linux, :func:`copystat` also copies the - "extended attributes" where possible. + Copy the permission bits, last access time, last modification time, and + flags from *src* to *dst*. On Linux, :func:`copystat` also copies the + "extended attributes" where possible. The file contents, owner, and + group are unaffected. *src* and *dst* are path names given as strings. + + If *follow_symlinks* is false, and *src* and *dst* both + refer to symbolic links, :func:`copystat` will operate on + the symbolic links themselves rather than the files the + symbolic links refer to--reading the information from the + *src* symbolic link, and writing the information to the + *dst* symbolic link. + + .. note:: + + Not all platforms provide the ability to examine and + modify symbolic links. Python itself can tell you what + functionality is locally available. + + * If ``os.chmod in os.supports_follow_symlinks`` is + ``True``, :func:`copystat` can modify the permission + bits of a symbolic link. + + * If ``os.utime in os.supports_follow_symlinks`` is + ``True``, :func:`copystat` can modify the last access + and modification times of a symbolic link. + + * If ``os.chflags in os.supports_follow_symlinks`` is + ``True``, :func:`copystat` can modify the flags of + a symbolic link. (``os.chflags`` is not available on + all platforms.) + + On platforms where some or all of this functionality + is unavailable, when asked to modify a symbolic link, + :func:`copystat` will copy everything it can. + :func:`copystat` never returns failure. + + Please see :data:`os.supports_follow_symlinks` + for more information. .. versionchanged:: 3.3 Added *follow_symlinks* argument and support for Linux extended attributes. .. function:: copy(src, dst, *, follow_symlinks=True) - Copy the file *src* to the file or directory *dst* and return the file's - destination. If *dst* is a directory, a - file with the same basename as *src* is created (or overwritten) in the - directory specified. Permission bits are copied. *src* and *dst* are path - names given as strings. If *follow_symlinks* is false, symbolic - links won't be followed but recreated instead -- this resembles GNU's - :program:`cp -P`. + Copies the file *src* to the file or directory *dst*. *src* and *dst* + should be strings. If *dst* specifies a directory, the file will be + copied into *dst* using the base filename from *src*. Returns the + path to the newly created file. + + If *follow_symlinks* is false, and *src* is a symbolic link, + *dst* will be created as a symbolic link. If *follow_symlinks* + is true and *src* is a symbolic link, *dst* will be a copy of + the file *src* refers to. + + :func:`copy` copies the file data and the file's permission + mode (see :func:`os.chmod`). Other metadata, like the + file's creation and modification times, is not preserved. + To preserve all file metadata from the original, use + :func:`~shutil.copy2` instead. .. versionchanged:: 3.3 Added *follow_symlinks* argument. - Now returns *dst*. + Now returns path to the newly created file. .. function:: copy2(src, dst, *, follow_symlinks=True) - Similar to :func:`shutil.copy`, including that the destination is - returned, but metadata is copied as well. This is similar to the Unix - command :program:`cp -p`. If *follow_symlinks* is false, - symbolic links won't be followed but recreated instead -- this resembles - GNU's :program:`cp -P`. + Identical to :func:`~shutil.copy` except that :func:`copy2` + also attempts to preserve all file metadata. + + When *follow_symlinks* is false, and *src* is a symbolic + link, :func:`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, :func:`copy2` will preserve all the metadata + it can; :func:`copy2` never returns failure. + + :func:`copy2` uses :func:`copystat` to copy the file metadata. + Please see :func:`copystat` for more information + about platform support for modifying symbolic link metadata. .. versionchanged:: 3.3 Added *follow_symlinks* argument, try to copy extended file system attributes too (currently Linux only). - Now returns *dst*. + Now returns path to the newly created file. .. function:: ignore_patterns(\*patterns)