diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/shutil.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/shutil.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,239 @@ + +:mod:`shutil` --- High-level file operations +============================================ + +.. module:: shutil + :synopsis: High-level file operations, including copying. +.. sectionauthor:: Fred L. Drake, Jr. +.. 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 +copying and removal. For operations on individual files, see also the +:mod:`os` module. + +.. warning:: + + Even the higher-level file copying functions (:func:`copy`, :func:`copy2`) + can't copy all file metadata. + + On POSIX platforms, this means that file owner and group are lost as well + as ACLs. On Mac OS, the resource fork and other metadata are not used. + This means that resources will be lost and file type and creator codes will + not be correct. On Windows, file owners, ACLs and alternate data streams + are not copied. + + +.. 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:: copyfile(src, dst) + + 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. + 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:: 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 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`. + + +.. function:: ignore_patterns(\*patterns) + + This factory function creates a function that can be used as a callable for + :func:`copytree`\'s *ignore* argument, ignoring files and directories that + match one of the glob-style *patterns* provided. See the example below. + + .. versionadded:: 2.6 + + +.. function:: copytree(src, dst[, symlinks=False[, ignore=None]]) + + 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 *ignore* is given, it must be a callable that will receive as its + arguments the directory being visited by :func:`copytree`, and a list of its + contents, as returned by :func:`os.listdir`. Since :func:`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. :func:`ignore_patterns` can be used to create such a callable that + ignores names based on glob-style patterns. + + 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 the + ultimate tool. + + .. versionchanged:: 2.3 + :exc:`Error` is raised if any exceptions occur during copying, rather than + printing a message. + + .. versionchanged:: 2.5 + Create intermediate directories needed to create *dst*, rather than raising an + error. Copy permissions and times of directories using :func:`copystat`. + + .. versionchanged:: 2.6 + Added the *ignore* argument to be able to influence what is being copied. + + +.. function:: rmtree(path[, ignore_errors[, onerror]]) + + .. index:: single: directory; deleting + + 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 *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.path.islink`, :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. + + .. versionchanged:: 2.6 + Explicitly check for *path* being a symbolic link and raise :exc:`OSError` + in that case. + + +.. function:: move(src, dst) + + Recursively move a file or directory to another location. + + If the destination is on the current filesystem, then simply use rename. + Otherwise, copy src to the dst and then remove src. + + .. versionadded:: 2.3 + + +.. exception:: Error + + This exception collects exceptions that raised during a multi-file operation. For + :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*, + *dstname*, *exception*). + + .. versionadded:: 2.3 + + +.. _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, ignore=None): + names = os.listdir(src) + if ignore is not None: + ignored_names = ignore(src, names) + else: + ignored_names = set() + + os.makedirs(dst) + errors = [] + for name in names: + if name in ignored_names: + continue + 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, ignore) + else: + copy2(srcname, dstname) + # XXX What about devices, sockets etc.? + except (IOError, os.error), why: + errors.append((srcname, dstname, str(why))) + # catch the Error from the recursive copytree so that we can + # continue with other files + except Error, err: + errors.extend(err.args[0]) + try: + copystat(src, dst) + except WindowsError: + # can't copy file access times on Windows + pass + except OSError, why: + errors.extend((src, dst, str(why))) + if errors: + raise Error, errors + +Another example that uses the :func:`ignore_patterns` helper:: + + from shutil import copytree, ignore_patterns + + copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*')) + +This will copy everything except ``.pyc`` files and files or directories whose +name starts with ``tmp``. + +Another example that uses the *ignore* argument to add a logging call:: + + from shutil import copytree + import logging + + def _logpath(path, names): + logging.info('Working in %s' % path) + return [] # nothing will be ignored + + copytree(source, destination, ignore=_logpath) +