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.
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)
.. 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
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
: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
projects / python / commitdiff