cpython/Doc/library/shutil.rst

163 lines
6.0 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`shutil` --- High-level file operations
============================================
.. module:: shutil
:synopsis: High-level file operations, including copying.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. % partly based on the docstrings
.. index::
single: file; copying
single: copying files
The :mod:`shutil` module offers a number of high-level operations on files and
collections of files. In particular, functions are provided which support file
Merged revisions 58742-58816 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r58745 | georg.brandl | 2007-11-01 10:19:33 -0700 (Thu, 01 Nov 2007) | 2 lines #1364: os.lstat is available on Windows too, as an alias to os.stat. ........ r58750 | christian.heimes | 2007-11-01 12:48:10 -0700 (Thu, 01 Nov 2007) | 1 line Backport of import tests for bug http://bugs.python.org/issue1293 and bug http://bugs.python.org/issue1342 ........ r58751 | christian.heimes | 2007-11-01 13:11:06 -0700 (Thu, 01 Nov 2007) | 1 line Removed non ASCII text from test as requested by Guido. Sorry :/ ........ r58753 | georg.brandl | 2007-11-01 13:37:02 -0700 (Thu, 01 Nov 2007) | 2 lines Fix markup glitch. ........ r58757 | gregory.p.smith | 2007-11-01 14:08:14 -0700 (Thu, 01 Nov 2007) | 4 lines Fix bug introduced in revision 58385. Database keys could no longer have NULL bytes in them. Replace the errant strdup with a malloc+memcpy. Adds a unit test for the correct behavior. ........ r58758 | gregory.p.smith | 2007-11-01 14:15:36 -0700 (Thu, 01 Nov 2007) | 3 lines Undo revision 58533 58534 fixes. Those were a workaround for a problem introduced by 58385. ........ r58759 | gregory.p.smith | 2007-11-01 14:17:47 -0700 (Thu, 01 Nov 2007) | 2 lines false "fix" undone as correct problem was found and fixed. ........ r58765 | mark.summerfield | 2007-11-02 01:24:59 -0700 (Fri, 02 Nov 2007) | 3 lines Added more file-handling related cross-references. ........ r58766 | nick.coghlan | 2007-11-02 03:09:12 -0700 (Fri, 02 Nov 2007) | 1 line Fix for bug 1705170 - contextmanager swallowing StopIteration (2.5 backport candidate) ........ r58784 | thomas.heller | 2007-11-02 12:10:24 -0700 (Fri, 02 Nov 2007) | 4 lines Issue #1292: On alpha, arm, ppc, and s390 linux systems the --with-system-ffi configure option defaults to "yes" because the bundled libffi sources are too old. ........ r58785 | thomas.heller | 2007-11-02 12:11:23 -0700 (Fri, 02 Nov 2007) | 1 line Enable the full ctypes c_longdouble tests again. ........ r58796 | georg.brandl | 2007-11-02 13:06:17 -0700 (Fri, 02 Nov 2007) | 4 lines Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__. I hope the concept of hashability is better understandable now. Thanks to Tim Hatch for pointing out the flaws here. ........
2007-11-02 20:46:40 -03:00
copying and removal. For operations on individual files, see also the
:mod:`os` module.
2007-08-15 11:28:22 -03:00
.. warning::
On MacOS, the resource fork and other metadata are not used. For file copies,
this means that resources will be lost and file type and creator codes will
not be correct.
2007-08-15 11:28:22 -03:00
.. function:: copyfile(src, dst)
Copy the contents of the file named *src* to a file named *dst*. The
destination location must be writable; otherwise, an :exc:`IOError` 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.
.. function:: copyfileobj(fsrc, fdst[, length])
Copy the contents of the file-like object *fsrc* to the file-like object *fdst*.
The integer *length*, if given, is the buffer size. In particular, a negative
*length* value means to copy the data without looping over the source data in
chunks; by default the data is read in chunks to avoid uncontrolled memory
consumption. Note that if the current file position of the *fsrc* object is not
0, only the contents from the current file position to the end of the file will
be copied.
.. function:: copymode(src, dst)
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.
.. function:: copystat(src, dst)
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.
.. function:: copy(src, dst)
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.
.. function:: copy2(src, dst)
Similar to :func:`copy`, but last access time and last modification time are
copied as well. This is similar to the Unix command :program:`cp -p`.
.. function:: copytree(src, dst[, symlinks])
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`. If
*symlinks* is true, symbolic links in the source tree are represented as
symbolic links in the new tree; if false or omitted, the contents of the linked
files are copied to the new tree. If exception(s) occur, an :exc:`Error` is
raised with a list of reasons.
The source code for this should be considered an example rather than a tool.
2007-08-15 11:28:22 -03:00
.. function:: rmtree(path[, ignore_errors[, onerror]])
.. index:: single: directory; deleting
Delete an entire directory tree (*path* must point 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
*onerror* or, if that is omitted, they raise an exception.
If *onerror* is provided, it must be a callable that accepts three parameters:
*function*, *path*, and *excinfo*. The first parameter, *function*, is the
function which raised the exception; it will be :func:`os.listdir`,
:func:`os.remove` or :func:`os.rmdir`. The second parameter, *path*, will be
the path name passed to *function*. The third parameter, *excinfo*, will be the
exception information return by :func:`sys.exc_info`. Exceptions raised by
*onerror* will not be caught.
.. function:: move(src, dst)
Recursively move a file or directory to another location.
If the destination is on our current filesystem, then simply use rename.
Otherwise, copy src to the dst and then remove src.
.. exception:: Error
This exception collects exceptions that raised during a mult-file operation. For
:func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
*dstname*, *exception*).
.. _shutil-example:
Example
-------
This example is the implementation of the :func:`copytree` function, described
above, with the docstring omitted. It demonstrates many of the other functions
provided by this module. ::
def copytree(src, dst, symlinks=False):
names = os.listdir(src)
os.makedirs(dst)
errors = []
for name in names:
srcname = os.path.join(src, name)
dstname = os.path.join(dst, name)
try:
if symlinks and os.path.islink(srcname):
linkto = os.readlink(srcname)
os.symlink(linkto, dstname)
elif os.path.isdir(srcname):
copytree(srcname, dstname, symlinks)
else:
copy2(srcname, dstname)
# XXX What about devices, sockets etc.?
except (IOError, os.error) as why:
errors.append((srcname, dstname, str(why)))
# catch the Error from the recursive copytree so that we can
# continue with other files
except Error as err:
errors.extend(err.args[0])
try:
copystat(src, dst)
except WindowsError:
# can't copy file access times on Windows
pass
except OSError as why:
errors.extend((src, dst, str(why)))
if errors:
raise Error(errors)
2007-08-15 11:28:22 -03:00