From: Senthil Kumaran Date: Mon, 13 Feb 2012 15:35:44 +0000 (+0800) Subject: shutil copy module reference doc fix. X-Git-Tag: v3.3.0a1~193 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=1fd648212e68b83a8bbd7fb628ee2607a5b3a69d;p=python shutil copy module reference doc fix. --- 1fd648212e68b83a8bbd7fb628ee2607a5b3a69d diff --cc Doc/library/shutil.rst index bae7db8e37,18f6485184..21ee94fc2a --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@@ -47,13 -47,13 +47,14 @@@ Directory and files operation be copied. -.. function:: copyfile(src, dst) +.. function:: copyfile(src, dst[, symlinks=False]) - Copy the contents (no metadata) of the file named *src* to a file named *dst*. - *dst* must be the complete target file name; look at :func:`copy` for a copy that - accepts a target directory path. If *src* and *dst* are the same files, - :exc:`Error` is raised. + Copy the contents (no metadata) of the file named *src* to a file named + *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. - The destination location must be writable; otherwise, an :exc:`IOError` exception ++ + 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. @@@ -93,21 -77,15 +94,22 @@@ Copy the file *src* to the file or directory *dst*. 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. + names given as strings. If *symlinks* is true, symbolic links won't be + followed but recreated instead -- this resembles GNU's :program:`cp -P`. + .. versionchanged:: 3.3 + Added *symlinks* argument. -.. function:: copy2(src, dst) +.. function:: copy2(src, dst[, symlinks=False]) - Similar to :func:`copy`, but metadata is copied as well -- in fact, this is just - :func:`copy` followed by :func:`copystat`. This is similar to the - Unix command :program:`cp -p`. If *symlinks* is true, symbolic links won't - be followed but recreated instead -- this resembles GNU's :program:`cp -P`. + Similar to :func:`shutil.copy`, but metadata is copied as well -- in fact, + this is just :func:`shutil.copy` followed by :func:`copystat`. This is - similar to the Unix command :program:`cp -p`. ++ similar to the Unix command :program:`cp -p`. If *symlinks* is true, ++ symbolic links won't be followed but recreated instead -- this resembles ++ GNU's :program:`cp -P`. + .. versionchanged:: 3.3 + Added *symlinks* argument. .. function:: ignore_patterns(\*patterns) @@@ -119,15 -97,15 +121,15 @@@ .. function:: copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False) Recursively copy an entire directory tree rooted at *src*. The destination - directory, named by *dst*, must not already exist; it will be created as well - as missing parent directories. Permissions and times of directories are - copied with :func:`copystat`, individual files are copied using - :func:`copy2`. + directory, named by *dst*, must not already exist; it will be created as + well as missing parent directories. Permissions and times of directories + are copied with :func:`copystat`, individual files are copied using + :func:`shutil.copy2`. If *symlinks* is true, symbolic links in the source tree are represented as - symbolic links in the new tree, but the metadata of the original links is NOT - copied; if false or omitted, the contents and metadata of the linked files - are copied to the new tree. + 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. When *symlinks* is false, if the file pointed by the symlink doesn't exist, a exception will be added in the list of errors raised in @@@ -148,10 -126,10 +150,10 @@@ If exception(s) occur, an :exc:`Error` is raised with a list of reasons. - If *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, :func:`copy2` is used, but any - function that supports the same signature (like :func:`copy`) can be used. + If *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, :func:`shutil.copy2` is used, but any function - that supports the same signature (like :func:`copy`) can be used. ++ that supports the same signature (like :func:`shutil.copy`) can be used. .. versionchanged:: 3.2 Added the *copy_function* argument to be able to provide a custom copy @@@ -197,36 -172,8 +199,36 @@@ :func:`os.rename` semantics. If the destination is on the current filesystem, then :func:`os.rename` is - used. Otherwise, *src* is copied (using :func:`copy2`) to *dst* and then - removed. In case of symlinks, a new symlink pointing to the target of *src* - will be created in or as *dst* and *src* will be removed. + used. Otherwise, *src* is copied (using :func:`shutil.copy2`) to *dst* and - then removed. ++ then removed. In case of symlinks, a new symlink pointing to the target of ++ *src* will be created in or as *dst* and *src* will be removed. + + .. versionchanged:: 3.3 + Added explicit symlink handling for foreign filesystems, thus adapting + it to the behavior of GNU's :program:`mv`. + +.. function:: disk_usage(path) + + Return disk usage statistics about the given path as a :term:`named tuple` + with the attributes *total*, *used* and *free*, which are the amount of + total, used and free space, in bytes. + + .. versionadded:: 3.3 + + Availability: Unix, Windows. + +.. function:: chown(path, user=None, group=None) + + Change owner *user* and/or *group* of the given *path*. + + *user* can be a system user name or a uid; the same applies to *group*. At + least one argument is required. + + See also :func:`os.chown`, the underlying function. + + Availability: Unix. + + .. versionadded:: 3.3 .. exception:: Error