Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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> |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 8 | .. partly based on the docstrings |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 9 | |
| 10 | .. index:: |
| 11 | single: file; copying |
| 12 | single: copying files |
| 13 | |
| 14 | The :mod:`shutil` module offers a number of high-level operations on files and |
| 15 | collections of files. In particular, functions are provided which support file |
Guido van Rossum | 2cc30da | 2007-11-02 23:46:40 +0000 | [diff] [blame] | 16 | copying and removal. For operations on individual files, see also the |
| 17 | :mod:`os` module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 18 | |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 19 | .. warning:: |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 20 | |
| 21 | Even the higher-level file copying functions (:func:`copy`, :func:`copy2`) |
| 22 | can't copy all file metadata. |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 23 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 24 | On POSIX platforms, this means that file owner and group are lost as well |
| 25 | as ACLs. On MacOS, 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | |
| 30 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 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. |
| 47 | The destination location must be writable; otherwise, an :exc:`IOError` exception |
| 48 | will be raised. If *dst* already exists, it will be replaced. Special files |
| 49 | such as character or block devices and pipes cannot be copied with this |
| 50 | function. *src* and *dst* are path names given as strings. |
| 51 | |
| 52 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | .. function:: copymode(src, dst) |
| 54 | |
| 55 | Copy the permission bits from *src* to *dst*. The file contents, owner, and |
| 56 | group are unaffected. *src* and *dst* are path names given as strings. |
| 57 | |
| 58 | |
| 59 | .. function:: copystat(src, dst) |
| 60 | |
| 61 | Copy the permission bits, last access time, last modification time, and flags |
| 62 | from *src* to *dst*. The file contents, owner, and group are unaffected. *src* |
| 63 | and *dst* are path names given as strings. |
| 64 | |
| 65 | |
| 66 | .. function:: copy(src, dst) |
| 67 | |
| 68 | Copy the file *src* to the file or directory *dst*. If *dst* is a directory, a |
| 69 | file with the same basename as *src* is created (or overwritten) in the |
| 70 | directory specified. Permission bits are copied. *src* and *dst* are path |
| 71 | names given as strings. |
| 72 | |
| 73 | |
| 74 | .. function:: copy2(src, dst) |
| 75 | |
Alexandre Vassalotti | bee3253 | 2008-05-16 18:15:12 +0000 | [diff] [blame] | 76 | Similar to :func:`copy`, but metadata is copied as well -- in fact, this is just |
| 77 | :func:`copy` followed by :func:`copystat`. This is similar to the |
| 78 | Unix command :program:`cp -p`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
| 80 | |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 81 | .. function:: ignore_patterns(\*patterns) |
| 82 | |
| 83 | This factory function creates a function that can be used as a callable for |
| 84 | :func:`copytree`\'s *ignore* argument, ignoring files and directories that |
| 85 | match one of the glob-style *patterns* provided. See the example below. |
| 86 | |
| 87 | |
| 88 | .. function:: copytree(src, dst[, symlinks=False[, ignore=None]]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
| 90 | Recursively copy an entire directory tree rooted at *src*. The destination |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 91 | directory, named by *dst*, must not already exist; it will be created as well |
| 92 | as missing parent directories. Permissions and times of directories are |
| 93 | copied with :func:`copystat`, individual files are copied using |
| 94 | :func:`copy2`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 96 | If *symlinks* is true, symbolic links in the source tree are represented as |
| 97 | symbolic links in the new tree; if false or omitted, the contents of the |
| 98 | linked files are copied to the new tree. |
| 99 | |
| 100 | If *ignore* is given, it must be a callable that will receive as its |
| 101 | arguments the directory being visited by :func:`copytree`, and a list of its |
| 102 | contents, as returned by :func:`os.listdir`. Since :func:`copytree` is |
| 103 | called recursively, the *ignore* callable will be called once for each |
| 104 | directory that is copied. The callable must return a sequence of directory |
| 105 | and file names relative to the current directory (i.e. a subset of the items |
| 106 | in its second argument); these names will then be ignored in the copy |
| 107 | process. :func:`ignore_patterns` can be used to create such a callable that |
| 108 | ignores names based on glob-style patterns. |
| 109 | |
| 110 | If exception(s) occur, an :exc:`Error` is raised with a list of reasons. |
| 111 | |
| 112 | The source code for this should be considered an example rather than the |
| 113 | ultimate tool. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
| 115 | |
| 116 | .. function:: rmtree(path[, ignore_errors[, onerror]]) |
| 117 | |
| 118 | .. index:: single: directory; deleting |
| 119 | |
Christian Heimes | 9bd667a | 2008-01-20 15:14:11 +0000 | [diff] [blame] | 120 | Delete an entire directory tree; *path* must point to a directory (but not a |
| 121 | symbolic link to a directory). If *ignore_errors* is true, errors resulting |
| 122 | from failed removals will be ignored; if false or omitted, such errors are |
| 123 | handled by calling a handler specified by *onerror* or, if that is omitted, |
| 124 | they raise an exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | |
Christian Heimes | 9bd667a | 2008-01-20 15:14:11 +0000 | [diff] [blame] | 126 | If *onerror* is provided, it must be a callable that accepts three |
| 127 | parameters: *function*, *path*, and *excinfo*. The first parameter, |
| 128 | *function*, is the function which raised the exception; it will be |
| 129 | :func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or |
| 130 | :func:`os.rmdir`. The second parameter, *path*, will be the path name passed |
| 131 | to *function*. The third parameter, *excinfo*, will be the exception |
| 132 | information return by :func:`sys.exc_info`. Exceptions raised by *onerror* |
| 133 | will not be caught. |
| 134 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 135 | |
| 136 | .. function:: move(src, dst) |
| 137 | |
| 138 | Recursively move a file or directory to another location. |
| 139 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 140 | If the destination is on the current filesystem, then simply use rename. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | Otherwise, copy src to the dst and then remove src. |
| 142 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
| 144 | .. exception:: Error |
| 145 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 146 | This exception collects exceptions that raised during a multi-file operation. For |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*, |
| 148 | *dstname*, *exception*). |
| 149 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
| 151 | .. _shutil-example: |
| 152 | |
| 153 | Example |
| 154 | ------- |
| 155 | |
| 156 | This example is the implementation of the :func:`copytree` function, described |
| 157 | above, with the docstring omitted. It demonstrates many of the other functions |
| 158 | provided by this module. :: |
| 159 | |
| 160 | def copytree(src, dst, symlinks=False): |
| 161 | names = os.listdir(src) |
| 162 | os.makedirs(dst) |
| 163 | errors = [] |
| 164 | for name in names: |
| 165 | srcname = os.path.join(src, name) |
| 166 | dstname = os.path.join(dst, name) |
| 167 | try: |
| 168 | if symlinks and os.path.islink(srcname): |
| 169 | linkto = os.readlink(srcname) |
| 170 | os.symlink(linkto, dstname) |
| 171 | elif os.path.isdir(srcname): |
| 172 | copytree(srcname, dstname, symlinks) |
| 173 | else: |
| 174 | copy2(srcname, dstname) |
| 175 | # XXX What about devices, sockets etc.? |
| 176 | except (IOError, os.error) as why: |
| 177 | errors.append((srcname, dstname, str(why))) |
| 178 | # catch the Error from the recursive copytree so that we can |
| 179 | # continue with other files |
| 180 | except Error as err: |
| 181 | errors.extend(err.args[0]) |
| 182 | try: |
| 183 | copystat(src, dst) |
| 184 | except WindowsError: |
| 185 | # can't copy file access times on Windows |
| 186 | pass |
| 187 | except OSError as why: |
| 188 | errors.extend((src, dst, str(why))) |
| 189 | if errors: |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 190 | raise Error(errors) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 191 | |