/Doc/library/shutil.rst
ReStructuredText | 240 lines | 171 code | 69 blank | 0 comment | 0 complexity | dd147b946c6dd983e06fb3016dac7b4d MD5 | raw file
1 2:mod:`shutil` --- High-level file operations 3============================================ 4 5.. module:: shutil 6 :synopsis: High-level file operations, including copying. 7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 8.. partly based on the docstrings 9 10.. index:: 11 single: file; copying 12 single: copying files 13 14The :mod:`shutil` module offers a number of high-level operations on files and 15collections of files. In particular, functions are provided which support file 16copying and removal. For operations on individual files, see also the 17:mod:`os` module. 18 19.. warning:: 20 21 Even the higher-level file copying functions (:func:`copy`, :func:`copy2`) 22 can't copy all file metadata. 23 24 On POSIX platforms, this means that file owner and group are lost as well 25 as ACLs. On Mac OS, the resource fork and other metadata are not used. 26 This means that resources will be lost and file type and creator codes will 27 not be correct. On Windows, file owners, ACLs and alternate data streams 28 are not copied. 29 30 31.. function:: copyfileobj(fsrc, fdst[, length]) 32 33 Copy the contents of the file-like object *fsrc* to the file-like object *fdst*. 34 The integer *length*, if given, is the buffer size. In particular, a negative 35 *length* value means to copy the data without looping over the source data in 36 chunks; by default the data is read in chunks to avoid uncontrolled memory 37 consumption. Note that if the current file position of the *fsrc* object is not 38 0, only the contents from the current file position to the end of the file will 39 be copied. 40 41 42.. function:: copyfile(src, dst) 43 44 Copy the contents (no metadata) of the file named *src* to a file named *dst*. 45 *dst* must be the complete target file name; look at :func:`copy` for a copy that 46 accepts a target directory path. If *src* and *dst* are the same files, 47 :exc:`Error` is raised. 48 The destination location must be writable; otherwise, an :exc:`IOError` exception 49 will be raised. If *dst* already exists, it will be replaced. Special files 50 such as character or block devices and pipes cannot be copied with this 51 function. *src* and *dst* are path names given as strings. 52 53 54.. function:: copymode(src, dst) 55 56 Copy the permission bits from *src* to *dst*. The file contents, owner, and 57 group are unaffected. *src* and *dst* are path names given as strings. 58 59 60.. function:: copystat(src, dst) 61 62 Copy the permission bits, last access time, last modification time, and flags 63 from *src* to *dst*. The file contents, owner, and group are unaffected. *src* 64 and *dst* are path names given as strings. 65 66 67.. function:: copy(src, dst) 68 69 Copy the file *src* to the file or directory *dst*. If *dst* is a directory, a 70 file with the same basename as *src* is created (or overwritten) in the 71 directory specified. Permission bits are copied. *src* and *dst* are path 72 names given as strings. 73 74 75.. function:: copy2(src, dst) 76 77 Similar to :func:`copy`, but metadata is copied as well -- in fact, this is just 78 :func:`copy` followed by :func:`copystat`. This is similar to the 79 Unix command :program:`cp -p`. 80 81 82.. function:: ignore_patterns(\*patterns) 83 84 This factory function creates a function that can be used as a callable for 85 :func:`copytree`\'s *ignore* argument, ignoring files and directories that 86 match one of the glob-style *patterns* provided. See the example below. 87 88 .. versionadded:: 2.6 89 90 91.. function:: copytree(src, dst[, symlinks=False[, ignore=None]]) 92 93 Recursively copy an entire directory tree rooted at *src*. The destination 94 directory, named by *dst*, must not already exist; it will be created as well 95 as missing parent directories. Permissions and times of directories are 96 copied with :func:`copystat`, individual files are copied using 97 :func:`copy2`. 98 99 If *symlinks* is true, symbolic links in the source tree are represented as 100 symbolic links in the new tree; if false or omitted, the contents of the 101 linked files are copied to the new tree. 102 103 If *ignore* is given, it must be a callable that will receive as its 104 arguments the directory being visited by :func:`copytree`, and a list of its 105 contents, as returned by :func:`os.listdir`. Since :func:`copytree` is 106 called recursively, the *ignore* callable will be called once for each 107 directory that is copied. The callable must return a sequence of directory 108 and file names relative to the current directory (i.e. a subset of the items 109 in its second argument); these names will then be ignored in the copy 110 process. :func:`ignore_patterns` can be used to create such a callable that 111 ignores names based on glob-style patterns. 112 113 If exception(s) occur, an :exc:`Error` is raised with a list of reasons. 114 115 The source code for this should be considered an example rather than the 116 ultimate tool. 117 118 .. versionchanged:: 2.3 119 :exc:`Error` is raised if any exceptions occur during copying, rather than 120 printing a message. 121 122 .. versionchanged:: 2.5 123 Create intermediate directories needed to create *dst*, rather than raising an 124 error. Copy permissions and times of directories using :func:`copystat`. 125 126 .. versionchanged:: 2.6 127 Added the *ignore* argument to be able to influence what is being copied. 128 129 130.. function:: rmtree(path[, ignore_errors[, onerror]]) 131 132 .. index:: single: directory; deleting 133 134 Delete an entire directory tree; *path* must point to a directory (but not a 135 symbolic link to a directory). If *ignore_errors* is true, errors resulting 136 from failed removals will be ignored; if false or omitted, such errors are 137 handled by calling a handler specified by *onerror* or, if that is omitted, 138 they raise an exception. 139 140 If *onerror* is provided, it must be a callable that accepts three 141 parameters: *function*, *path*, and *excinfo*. The first parameter, 142 *function*, is the function which raised the exception; it will be 143 :func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or 144 :func:`os.rmdir`. The second parameter, *path*, will be the path name passed 145 to *function*. The third parameter, *excinfo*, will be the exception 146 information return by :func:`sys.exc_info`. Exceptions raised by *onerror* 147 will not be caught. 148 149 .. versionchanged:: 2.6 150 Explicitly check for *path* being a symbolic link and raise :exc:`OSError` 151 in that case. 152 153 154.. function:: move(src, dst) 155 156 Recursively move a file or directory to another location. 157 158 If the destination is on the current filesystem, then simply use rename. 159 Otherwise, copy src (with :func:`copy2`) to the dst and then remove src. 160 161 .. versionadded:: 2.3 162 163 164.. exception:: Error 165 166 This exception collects exceptions that raised during a multi-file operation. For 167 :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*, 168 *dstname*, *exception*). 169 170 .. versionadded:: 2.3 171 172 173.. _shutil-example: 174 175Example 176------- 177 178This example is the implementation of the :func:`copytree` function, described 179above, with the docstring omitted. It demonstrates many of the other functions 180provided by this module. :: 181 182 def copytree(src, dst, symlinks=False, ignore=None): 183 names = os.listdir(src) 184 if ignore is not None: 185 ignored_names = ignore(src, names) 186 else: 187 ignored_names = set() 188 189 os.makedirs(dst) 190 errors = [] 191 for name in names: 192 if name in ignored_names: 193 continue 194 srcname = os.path.join(src, name) 195 dstname = os.path.join(dst, name) 196 try: 197 if symlinks and os.path.islink(srcname): 198 linkto = os.readlink(srcname) 199 os.symlink(linkto, dstname) 200 elif os.path.isdir(srcname): 201 copytree(srcname, dstname, symlinks, ignore) 202 else: 203 copy2(srcname, dstname) 204 # XXX What about devices, sockets etc.? 205 except (IOError, os.error), why: 206 errors.append((srcname, dstname, str(why))) 207 # catch the Error from the recursive copytree so that we can 208 # continue with other files 209 except Error, err: 210 errors.extend(err.args[0]) 211 try: 212 copystat(src, dst) 213 except WindowsError: 214 # can't copy file access times on Windows 215 pass 216 except OSError, why: 217 errors.extend((src, dst, str(why))) 218 if errors: 219 raise Error, errors 220 221Another example that uses the :func:`ignore_patterns` helper:: 222 223 from shutil import copytree, ignore_patterns 224 225 copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*')) 226 227This will copy everything except ``.pyc`` files and files or directories whose 228name starts with ``tmp``. 229 230Another example that uses the *ignore* argument to add a logging call:: 231 232 from shutil import copytree 233 import logging 234 235 def _logpath(path, names): 236 logging.info('Working in %s' % path) 237 return [] # nothing will be ignored 238 239 copytree(source, destination, ignore=_logpath) 240