Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`shutil` --- High-level file operations |
| 2 | ============================================ |
| 3 | |
| 4 | .. module:: shutil |
| 5 | :synopsis: High-level file operations, including copying. |
| 6 | .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 7 | .. partly based on the docstrings |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | |
| 9 | .. index:: |
| 10 | single: file; copying |
| 11 | single: copying files |
| 12 | |
Raymond Hettinger | 1048094 | 2011-01-10 03:26:08 +0000 | [diff] [blame] | 13 | **Source code:** :source:`Lib/shutil.py` |
| 14 | |
Raymond Hettinger | 4f707fd | 2011-01-10 19:54:11 +0000 | [diff] [blame] | 15 | -------------- |
| 16 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | The :mod:`shutil` module offers a number of high-level operations on files and |
| 18 | collections of files. In particular, functions are provided which support file |
Guido van Rossum | 2cc30da | 2007-11-02 23:46:40 +0000 | [diff] [blame] | 19 | copying and removal. For operations on individual files, see also the |
| 20 | :mod:`os` module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 22 | .. warning:: |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 23 | |
Senthil Kumaran | 7f728c1 | 2012-02-13 23:30:47 +0800 | [diff] [blame] | 24 | Even the higher-level file copying functions (:func:`shutil.copy`, |
| 25 | :func:`shutil.copy2`) cannot copy all file metadata. |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 26 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 27 | On POSIX platforms, this means that file owner and group are lost as well |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 28 | as ACLs. On Mac OS, the resource fork and other metadata are not used. |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 29 | This means that resources will be lost and file type and creator codes will |
| 30 | not be correct. On Windows, file owners, ACLs and alternate data streams |
| 31 | are not copied. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | |
Éric Araujo | 6e6cb8e | 2010-11-16 19:13:50 +0000 | [diff] [blame] | 33 | |
Éric Araujo | f2fbb9c | 2012-01-16 16:55:55 +0100 | [diff] [blame] | 34 | .. _file-operations: |
| 35 | |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 36 | Directory and files operations |
| 37 | ------------------------------ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | .. function:: copyfileobj(fsrc, fdst[, length]) |
| 40 | |
| 41 | Copy the contents of the file-like object *fsrc* to the file-like object *fdst*. |
| 42 | The integer *length*, if given, is the buffer size. In particular, a negative |
| 43 | *length* value means to copy the data without looping over the source data in |
| 44 | chunks; by default the data is read in chunks to avoid uncontrolled memory |
| 45 | consumption. Note that if the current file position of the *fsrc* object is not |
| 46 | 0, only the contents from the current file position to the end of the file will |
| 47 | be copied. |
| 48 | |
| 49 | |
Hynek Schlawack | 6e49ac2 | 2012-05-21 13:41:25 +0200 | [diff] [blame] | 50 | .. function:: copyfile(src, dst, symlinks=False) |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 51 | |
Senthil Kumaran | 7f728c1 | 2012-02-13 23:30:47 +0800 | [diff] [blame] | 52 | Copy the contents (no metadata) of the file named *src* to a file named |
Brian Curtin | 0d0a1de | 2012-06-18 18:41:07 -0500 | [diff] [blame] | 53 | *dst* and return *dst*. *dst* must be the complete target file name; look at |
Senthil Kumaran | 7f728c1 | 2012-02-13 23:30:47 +0800 | [diff] [blame] | 54 | :func:`shutil.copy` for a copy that accepts a target directory path. If |
| 55 | *src* and *dst* are the same files, :exc:`Error` is raised. |
Senthil Kumaran | 1fd6482 | 2012-02-13 23:35:44 +0800 | [diff] [blame] | 56 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 57 | The destination location must be writable; otherwise, an :exc:`OSError` exception |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 58 | will be raised. If *dst* already exists, it will be replaced. Special files |
| 59 | such as character or block devices and pipes cannot be copied with this |
| 60 | function. *src* and *dst* are path names given as strings. |
| 61 | |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 62 | If *symlinks* is true and *src* is a symbolic link, a new symbolic link will |
| 63 | be created instead of copying the file *src* points to. |
| 64 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 65 | .. versionchanged:: 3.3 |
| 66 | :exc:`IOError` used to be raised instead of :exc:`OSError`. |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 67 | Added *symlinks* argument. |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 68 | |
Brian Curtin | 066dacf | 2012-06-19 10:03:05 -0500 | [diff] [blame] | 69 | .. versionchanged:: 3.3 |
| 70 | Added return of the *dst*. |
Christian Heimes | a342c01 | 2008-04-20 21:01:16 +0000 | [diff] [blame] | 71 | |
Hynek Schlawack | 6e49ac2 | 2012-05-21 13:41:25 +0200 | [diff] [blame] | 72 | .. function:: copymode(src, dst, symlinks=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
| 74 | Copy the permission bits from *src* to *dst*. The file contents, owner, and |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 75 | group are unaffected. *src* and *dst* are path names given as strings. If |
| 76 | *symlinks* is true, *src* a symbolic link and the operating system supports |
| 77 | modes for symbolic links (for example BSD-based ones), the mode of the link |
| 78 | will be copied. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 80 | .. versionchanged:: 3.3 |
| 81 | Added *symlinks* argument. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 82 | |
Hynek Schlawack | 6e49ac2 | 2012-05-21 13:41:25 +0200 | [diff] [blame] | 83 | .. function:: copystat(src, dst, symlinks=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | Copy the permission bits, last access time, last modification time, and flags |
| 86 | from *src* to *dst*. The file contents, owner, and group are unaffected. *src* |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 87 | and *dst* are path names given as strings. If *src* and *dst* are both |
| 88 | symbolic links and *symlinks* true, the stats of the link will be copied as |
| 89 | far as the platform allows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 91 | .. versionchanged:: 3.3 |
| 92 | Added *symlinks* argument. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 93 | |
Hynek Schlawack | 6e49ac2 | 2012-05-21 13:41:25 +0200 | [diff] [blame] | 94 | .. function:: copy(src, dst, symlinks=False)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
Brian Curtin | 0d0a1de | 2012-06-18 18:41:07 -0500 | [diff] [blame] | 96 | Copy the file *src* to the file or directory *dst* and return the file's |
| 97 | destination. If *dst* is a directory, a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | file with the same basename as *src* is created (or overwritten) in the |
| 99 | directory specified. Permission bits are copied. *src* and *dst* are path |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 100 | names given as strings. If *symlinks* is true, symbolic links won't be |
| 101 | followed but recreated instead -- this resembles GNU's :program:`cp -P`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 103 | .. versionchanged:: 3.3 |
| 104 | Added *symlinks* argument. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
Brian Curtin | 066dacf | 2012-06-19 10:03:05 -0500 | [diff] [blame] | 106 | .. versionchanged:: 3.3 |
| 107 | Added return of the *dst*. |
| 108 | |
Hynek Schlawack | 6e49ac2 | 2012-05-21 13:41:25 +0200 | [diff] [blame] | 109 | .. function:: copy2(src, dst, symlinks=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
Brian Curtin | 0d0a1de | 2012-06-18 18:41:07 -0500 | [diff] [blame] | 111 | Similar to :func:`shutil.copy`, including that the destination is |
| 112 | returned, but metadata is copied as well. This is |
Senthil Kumaran | 1fd6482 | 2012-02-13 23:35:44 +0800 | [diff] [blame] | 113 | similar to the Unix command :program:`cp -p`. If *symlinks* is true, |
| 114 | symbolic links won't be followed but recreated instead -- this resembles |
| 115 | GNU's :program:`cp -P`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 117 | .. versionchanged:: 3.3 |
Antoine Pitrou | 424246f | 2012-05-12 19:02:01 +0200 | [diff] [blame] | 118 | Added *symlinks* argument, try to copy extended file system attributes |
| 119 | too (currently Linux only). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
Brian Curtin | 066dacf | 2012-06-19 10:03:05 -0500 | [diff] [blame] | 121 | .. versionchanged:: 3.3 |
| 122 | Added return of the *dst*. |
| 123 | |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 124 | .. function:: ignore_patterns(\*patterns) |
| 125 | |
| 126 | This factory function creates a function that can be used as a callable for |
| 127 | :func:`copytree`\'s *ignore* argument, ignoring files and directories that |
| 128 | match one of the glob-style *patterns* provided. See the example below. |
| 129 | |
| 130 | |
Ezio Melotti | cb999a3 | 2010-04-20 11:26:51 +0000 | [diff] [blame] | 131 | .. function:: copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 132 | |
Brian Curtin | 0d0a1de | 2012-06-18 18:41:07 -0500 | [diff] [blame] | 133 | Recursively copy an entire directory tree rooted at *src*, returning the |
| 134 | destination directory. The destination |
Senthil Kumaran | 7f728c1 | 2012-02-13 23:30:47 +0800 | [diff] [blame] | 135 | directory, named by *dst*, must not already exist; it will be created as |
| 136 | well as missing parent directories. Permissions and times of directories |
| 137 | are copied with :func:`copystat`, individual files are copied using |
| 138 | :func:`shutil.copy2`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 140 | If *symlinks* is true, symbolic links in the source tree are represented as |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 141 | symbolic links in the new tree and the metadata of the original links will |
| 142 | be copied as far as the platform allows; if false or omitted, the contents |
| 143 | and metadata of the linked files are copied to the new tree. |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 144 | |
Tarek Ziadé | fb43751 | 2010-04-20 08:57:33 +0000 | [diff] [blame] | 145 | When *symlinks* is false, if the file pointed by the symlink doesn't |
| 146 | exist, a exception will be added in the list of errors raised in |
| 147 | a :exc:`Error` exception at the end of the copy process. |
| 148 | You can set the optional *ignore_dangling_symlinks* flag to true if you |
Tarek Ziadé | 8c26c7d | 2010-04-23 13:03:50 +0000 | [diff] [blame] | 149 | want to silence this exception. Notice that this option has no effect |
| 150 | on platforms that don't support :func:`os.symlink`. |
Tarek Ziadé | fb43751 | 2010-04-20 08:57:33 +0000 | [diff] [blame] | 151 | |
Georg Brandl | 86b2fb9 | 2008-07-16 03:43:04 +0000 | [diff] [blame] | 152 | If *ignore* is given, it must be a callable that will receive as its |
| 153 | arguments the directory being visited by :func:`copytree`, and a list of its |
| 154 | contents, as returned by :func:`os.listdir`. Since :func:`copytree` is |
| 155 | called recursively, the *ignore* callable will be called once for each |
| 156 | directory that is copied. The callable must return a sequence of directory |
| 157 | and file names relative to the current directory (i.e. a subset of the items |
| 158 | in its second argument); these names will then be ignored in the copy |
| 159 | process. :func:`ignore_patterns` can be used to create such a callable that |
| 160 | ignores names based on glob-style patterns. |
| 161 | |
| 162 | If exception(s) occur, an :exc:`Error` is raised with a list of reasons. |
| 163 | |
Senthil Kumaran | 7f728c1 | 2012-02-13 23:30:47 +0800 | [diff] [blame] | 164 | If *copy_function* is given, it must be a callable that will be used to copy |
| 165 | each file. It will be called with the source path and the destination path |
| 166 | as arguments. By default, :func:`shutil.copy2` is used, but any function |
Senthil Kumaran | 1fd6482 | 2012-02-13 23:35:44 +0800 | [diff] [blame] | 167 | that supports the same signature (like :func:`shutil.copy`) can be used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 168 | |
Tarek Ziadé | 5340db3 | 2010-04-19 22:30:51 +0000 | [diff] [blame] | 169 | .. versionchanged:: 3.2 |
| 170 | Added the *copy_function* argument to be able to provide a custom copy |
| 171 | function. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 172 | |
Ezio Melotti | cb999a3 | 2010-04-20 11:26:51 +0000 | [diff] [blame] | 173 | .. versionchanged:: 3.2 |
Tarek Ziadé | fb43751 | 2010-04-20 08:57:33 +0000 | [diff] [blame] | 174 | Added the *ignore_dangling_symlinks* argument to silent dangling symlinks |
| 175 | errors when *symlinks* is false. |
| 176 | |
Antoine Pitrou | 78091e6 | 2011-12-29 18:54:15 +0100 | [diff] [blame] | 177 | .. versionchanged:: 3.3 |
| 178 | Copy metadata when *symlinks* is false. |
| 179 | |
Brian Curtin | 066dacf | 2012-06-19 10:03:05 -0500 | [diff] [blame] | 180 | .. versionchanged:: 3.3 |
| 181 | Added return of the *dst*. |
Tarek Ziadé | fb43751 | 2010-04-20 08:57:33 +0000 | [diff] [blame] | 182 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 183 | .. function:: rmtree(path, ignore_errors=False, onerror=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 184 | |
| 185 | .. index:: single: directory; deleting |
| 186 | |
Christian Heimes | 9bd667a | 2008-01-20 15:14:11 +0000 | [diff] [blame] | 187 | Delete an entire directory tree; *path* must point to a directory (but not a |
| 188 | symbolic link to a directory). If *ignore_errors* is true, errors resulting |
| 189 | from failed removals will be ignored; if false or omitted, such errors are |
| 190 | handled by calling a handler specified by *onerror* or, if that is omitted, |
| 191 | they raise an exception. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 192 | |
Hynek Schlawack | 67be92b | 2012-06-23 17:58:42 +0200 | [diff] [blame^] | 193 | .. warning:: |
| 194 | |
| 195 | The default :func:`rmtree` function is susceptible to a symlink attack: |
| 196 | given proper timing and circumstances, attackers can use it to delete |
| 197 | files they wouldn't be able to access otherwise. Thus -- on platforms |
| 198 | that support the necessary fd-based functions :func:`os.openat` and |
| 199 | :func:`os.unlinkat` -- a safe version of :func:`rmtree` is used, which |
| 200 | isn't vulnerable. |
| 201 | |
Christian Heimes | 9bd667a | 2008-01-20 15:14:11 +0000 | [diff] [blame] | 202 | If *onerror* is provided, it must be a callable that accepts three |
Hynek Schlawack | 67be92b | 2012-06-23 17:58:42 +0200 | [diff] [blame^] | 203 | parameters: *function*, *path*, and *excinfo*. |
| 204 | |
| 205 | The first parameter, *function*, is the function which raised the exception; |
| 206 | it depends on the platform and implementation. The second parameter, |
| 207 | *path*, will be the path name passed to *function*. The third parameter, |
| 208 | *excinfo*, will be the exception information returned by |
| 209 | :func:`sys.exc_info`. Exceptions raised by *onerror* will not be caught. |
| 210 | |
| 211 | .. versionchanged:: 3.3 |
| 212 | Added a safe version that is used automatically if platform supports |
| 213 | the fd-based functions :func:`os.openat` and :func:`os.unlinkat`. |
Christian Heimes | 9bd667a | 2008-01-20 15:14:11 +0000 | [diff] [blame] | 214 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 215 | |
| 216 | .. function:: move(src, dst) |
| 217 | |
Brian Curtin | 0d0a1de | 2012-06-18 18:41:07 -0500 | [diff] [blame] | 218 | Recursively move a file or directory (*src*) to another location (*dst*) |
| 219 | and return the destination. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 220 | |
Éric Araujo | 14382dc | 2011-07-28 22:49:11 +0200 | [diff] [blame] | 221 | If the destination is a directory or a symlink to a directory, then *src* is |
| 222 | moved inside that directory. |
| 223 | |
| 224 | The destination directory must not already exist. If the destination already |
| 225 | exists but is not a directory, it may be overwritten depending on |
| 226 | :func:`os.rename` semantics. |
| 227 | |
| 228 | If the destination is on the current filesystem, then :func:`os.rename` is |
Senthil Kumaran | 7f728c1 | 2012-02-13 23:30:47 +0800 | [diff] [blame] | 229 | used. Otherwise, *src* is copied (using :func:`shutil.copy2`) to *dst* and |
Senthil Kumaran | 1fd6482 | 2012-02-13 23:35:44 +0800 | [diff] [blame] | 230 | then removed. In case of symlinks, a new symlink pointing to the target of |
| 231 | *src* will be created in or as *dst* and *src* will be removed. |
Antoine Pitrou | 0a08d7a | 2012-01-06 20:16:19 +0100 | [diff] [blame] | 232 | |
| 233 | .. versionchanged:: 3.3 |
| 234 | Added explicit symlink handling for foreign filesystems, thus adapting |
| 235 | it to the behavior of GNU's :program:`mv`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 236 | |
Brian Curtin | 066dacf | 2012-06-19 10:03:05 -0500 | [diff] [blame] | 237 | .. versionchanged:: 3.3 |
| 238 | Added return of the *dst*. |
| 239 | |
Giampaolo Rodola' | 210e7ca | 2011-07-01 13:55:36 +0200 | [diff] [blame] | 240 | .. function:: disk_usage(path) |
| 241 | |
Éric Araujo | e4d5b8e | 2011-08-08 16:51:11 +0200 | [diff] [blame] | 242 | Return disk usage statistics about the given path as a :term:`named tuple` |
| 243 | with the attributes *total*, *used* and *free*, which are the amount of |
| 244 | total, used and free space, in bytes. |
Giampaolo Rodola' | 210e7ca | 2011-07-01 13:55:36 +0200 | [diff] [blame] | 245 | |
| 246 | .. versionadded:: 3.3 |
| 247 | |
| 248 | Availability: Unix, Windows. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 249 | |
Sandro Tosi | d902a14 | 2011-08-22 23:28:27 +0200 | [diff] [blame] | 250 | .. function:: chown(path, user=None, group=None) |
| 251 | |
| 252 | Change owner *user* and/or *group* of the given *path*. |
| 253 | |
| 254 | *user* can be a system user name or a uid; the same applies to *group*. At |
| 255 | least one argument is required. |
| 256 | |
| 257 | See also :func:`os.chown`, the underlying function. |
| 258 | |
| 259 | Availability: Unix. |
| 260 | |
| 261 | .. versionadded:: 3.3 |
| 262 | |
Brian Curtin | c57a345 | 2012-06-22 16:00:30 -0500 | [diff] [blame] | 263 | .. function:: which(cmd, mode=os.F_OK | os.X_OK, path=None) |
| 264 | |
Antoine Pitrou | 07c24d1 | 2012-06-22 23:33:05 +0200 | [diff] [blame] | 265 | Return the path to an executable which would be run if the given *cmd* |
| 266 | was called. If no *cmd* would be called, return ``None``. |
Brian Curtin | c57a345 | 2012-06-22 16:00:30 -0500 | [diff] [blame] | 267 | |
| 268 | *mode* is a permission mask passed a to :func:`os.access`, by default |
| 269 | determining if the file exists and executable. |
| 270 | |
| 271 | When no *path* is specified, the results of :func:`os.environ` are |
| 272 | used, returning either the "PATH" value or a fallback of :attr:`os.defpath`. |
| 273 | |
| 274 | On Windows, the current directory is always prepended to the *path* |
| 275 | whether or not you use the default or provide your own, which |
| 276 | is the behavior the command shell uses when finding executables. |
| 277 | Additionaly, when finding the *cmd* in the *path*, the |
| 278 | ``PATHEXT`` environment variable is checked. For example, if you |
| 279 | call ``shutil.which("python")``, :func:`which` will search |
| 280 | ``PATHEXT`` to know that it should look for ``python.exe`` within |
| 281 | the *path* directories. |
| 282 | |
| 283 | >>> print(shutil.which("python")) |
| 284 | 'c:\\python33\\python.exe' |
| 285 | |
| 286 | .. versionadded:: 3.3 |
Sandro Tosi | d902a14 | 2011-08-22 23:28:27 +0200 | [diff] [blame] | 287 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 288 | .. exception:: Error |
| 289 | |
Éric Araujo | 14382dc | 2011-07-28 22:49:11 +0200 | [diff] [blame] | 290 | This exception collects exceptions that are raised during a multi-file |
| 291 | operation. For :func:`copytree`, the exception argument is a list of 3-tuples |
| 292 | (*srcname*, *dstname*, *exception*). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 293 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 294 | |
Éric Araujo | f2fbb9c | 2012-01-16 16:55:55 +0100 | [diff] [blame] | 295 | .. _shutil-copytree-example: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 296 | |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 297 | copytree example |
| 298 | :::::::::::::::: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 299 | |
| 300 | This example is the implementation of the :func:`copytree` function, described |
| 301 | above, with the docstring omitted. It demonstrates many of the other functions |
| 302 | provided by this module. :: |
| 303 | |
| 304 | def copytree(src, dst, symlinks=False): |
| 305 | names = os.listdir(src) |
| 306 | os.makedirs(dst) |
| 307 | errors = [] |
| 308 | for name in names: |
| 309 | srcname = os.path.join(src, name) |
| 310 | dstname = os.path.join(dst, name) |
| 311 | try: |
| 312 | if symlinks and os.path.islink(srcname): |
| 313 | linkto = os.readlink(srcname) |
| 314 | os.symlink(linkto, dstname) |
| 315 | elif os.path.isdir(srcname): |
| 316 | copytree(srcname, dstname, symlinks) |
| 317 | else: |
| 318 | copy2(srcname, dstname) |
| 319 | # XXX What about devices, sockets etc.? |
| 320 | except (IOError, os.error) as why: |
| 321 | errors.append((srcname, dstname, str(why))) |
| 322 | # catch the Error from the recursive copytree so that we can |
| 323 | # continue with other files |
| 324 | except Error as err: |
| 325 | errors.extend(err.args[0]) |
| 326 | try: |
| 327 | copystat(src, dst) |
| 328 | except WindowsError: |
| 329 | # can't copy file access times on Windows |
| 330 | pass |
| 331 | except OSError as why: |
| 332 | errors.extend((src, dst, str(why))) |
| 333 | if errors: |
Collin Winter | c79461b | 2007-09-01 23:34:30 +0000 | [diff] [blame] | 334 | raise Error(errors) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 335 | |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 336 | Another example that uses the :func:`ignore_patterns` helper:: |
| 337 | |
| 338 | from shutil import copytree, ignore_patterns |
| 339 | |
| 340 | copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*')) |
| 341 | |
| 342 | This will copy everything except ``.pyc`` files and files or directories whose |
| 343 | name starts with ``tmp``. |
| 344 | |
| 345 | Another example that uses the *ignore* argument to add a logging call:: |
| 346 | |
| 347 | from shutil import copytree |
| 348 | import logging |
| 349 | |
| 350 | def _logpath(path, names): |
| 351 | logging.info('Working in %s' % path) |
| 352 | return [] # nothing will be ignored |
| 353 | |
| 354 | copytree(source, destination, ignore=_logpath) |
| 355 | |
| 356 | |
Raymond Hettinger | 0929b1f | 2011-01-23 11:29:08 +0000 | [diff] [blame] | 357 | .. _archiving-operations: |
| 358 | |
| 359 | Archiving operations |
| 360 | -------------------- |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 361 | |
Éric Araujo | f2fbb9c | 2012-01-16 16:55:55 +0100 | [diff] [blame] | 362 | High-level utilities to create and read compressed and archived files are also |
| 363 | provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. |
| 364 | |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 365 | .. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]]) |
| 366 | |
Raymond Hettinger | 0929b1f | 2011-01-23 11:29:08 +0000 | [diff] [blame] | 367 | Create an archive file (such as zip or tar) and return its name. |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 368 | |
| 369 | *base_name* is the name of the file to create, including the path, minus |
| 370 | any format-specific extension. *format* is the archive format: one of |
Tarek Ziadé | ffa155a | 2010-04-29 13:34:35 +0000 | [diff] [blame] | 371 | "zip", "tar", "bztar" (if the :mod:`bz2` module is available) or "gztar". |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 372 | |
| 373 | *root_dir* is a directory that will be the root directory of the |
Raymond Hettinger | 0929b1f | 2011-01-23 11:29:08 +0000 | [diff] [blame] | 374 | archive; for example, we typically chdir into *root_dir* before creating the |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 375 | archive. |
| 376 | |
| 377 | *base_dir* is the directory where we start archiving from; |
Ezio Melotti | cb999a3 | 2010-04-20 11:26:51 +0000 | [diff] [blame] | 378 | i.e. *base_dir* will be the common prefix of all files and |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 379 | directories in the archive. |
| 380 | |
| 381 | *root_dir* and *base_dir* both default to the current directory. |
| 382 | |
| 383 | *owner* and *group* are used when creating a tar archive. By default, |
| 384 | uses the current owner and group. |
| 385 | |
Éric Araujo | 06c42a3 | 2011-11-07 17:31:07 +0100 | [diff] [blame] | 386 | *logger* must be an object compatible with :pep:`282`, usually an instance of |
| 387 | :class:`logging.Logger`. |
Raymond Hettinger | 0929b1f | 2011-01-23 11:29:08 +0000 | [diff] [blame] | 388 | |
Ezio Melotti | f8754a6 | 2010-03-21 07:16:43 +0000 | [diff] [blame] | 389 | .. versionadded:: 3.2 |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 390 | |
| 391 | |
| 392 | .. function:: get_archive_formats() |
| 393 | |
Éric Araujo | 14382dc | 2011-07-28 22:49:11 +0200 | [diff] [blame] | 394 | Return a list of supported formats for archiving. |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 395 | Each element of the returned sequence is a tuple ``(name, description)`` |
| 396 | |
| 397 | By default :mod:`shutil` provides these formats: |
| 398 | |
| 399 | - *gztar*: gzip'ed tar-file |
Tarek Ziadé | ffa155a | 2010-04-29 13:34:35 +0000 | [diff] [blame] | 400 | - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available.) |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 401 | - *tar*: uncompressed tar file |
| 402 | - *zip*: ZIP file |
| 403 | |
| 404 | You can register new formats or provide your own archiver for any existing |
| 405 | formats, by using :func:`register_archive_format`. |
| 406 | |
Ezio Melotti | f8754a6 | 2010-03-21 07:16:43 +0000 | [diff] [blame] | 407 | .. versionadded:: 3.2 |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 408 | |
| 409 | |
| 410 | .. function:: register_archive_format(name, function, [extra_args, [description]]) |
| 411 | |
Éric Araujo | 14382dc | 2011-07-28 22:49:11 +0200 | [diff] [blame] | 412 | Register an archiver for the format *name*. *function* is a callable that |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 413 | will be used to invoke the archiver. |
| 414 | |
Raymond Hettinger | 0929b1f | 2011-01-23 11:29:08 +0000 | [diff] [blame] | 415 | If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 416 | used as extra keywords arguments when the archiver callable is used. |
| 417 | |
| 418 | *description* is used by :func:`get_archive_formats` which returns the |
| 419 | list of archivers. Defaults to an empty list. |
| 420 | |
Ezio Melotti | f8754a6 | 2010-03-21 07:16:43 +0000 | [diff] [blame] | 421 | .. versionadded:: 3.2 |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 422 | |
| 423 | |
Tarek Ziadé | 6ac9172 | 2010-04-28 17:51:36 +0000 | [diff] [blame] | 424 | .. function:: unregister_archive_format(name) |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 425 | |
| 426 | Remove the archive format *name* from the list of supported formats. |
| 427 | |
Ezio Melotti | f8754a6 | 2010-03-21 07:16:43 +0000 | [diff] [blame] | 428 | .. versionadded:: 3.2 |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 429 | |
| 430 | |
Tarek Ziadé | 6ac9172 | 2010-04-28 17:51:36 +0000 | [diff] [blame] | 431 | .. function:: unpack_archive(filename[, extract_dir[, format]]) |
| 432 | |
| 433 | Unpack an archive. *filename* is the full path of the archive. |
| 434 | |
| 435 | *extract_dir* is the name of the target directory where the archive is |
| 436 | unpacked. If not provided, the current working directory is used. |
| 437 | |
| 438 | *format* is the archive format: one of "zip", "tar", or "gztar". Or any |
| 439 | other format registered with :func:`register_unpack_format`. If not |
| 440 | provided, :func:`unpack_archive` will use the archive file name extension |
| 441 | and see if an unpacker was registered for that extension. In case none is |
| 442 | found, a :exc:`ValueError` is raised. |
| 443 | |
| 444 | .. versionadded:: 3.2 |
| 445 | |
| 446 | |
Raymond Hettinger | 0929b1f | 2011-01-23 11:29:08 +0000 | [diff] [blame] | 447 | .. function:: register_unpack_format(name, extensions, function[, extra_args[, description]]) |
Tarek Ziadé | 6ac9172 | 2010-04-28 17:51:36 +0000 | [diff] [blame] | 448 | |
| 449 | Registers an unpack format. *name* is the name of the format and |
| 450 | *extensions* is a list of extensions corresponding to the format, like |
| 451 | ``.zip`` for Zip files. |
| 452 | |
| 453 | *function* is the callable that will be used to unpack archives. The |
| 454 | callable will receive the path of the archive, followed by the directory |
| 455 | the archive must be extracted to. |
| 456 | |
| 457 | When provided, *extra_args* is a sequence of ``(name, value)`` tuples that |
| 458 | will be passed as keywords arguments to the callable. |
| 459 | |
| 460 | *description* can be provided to describe the format, and will be returned |
| 461 | by the :func:`get_unpack_formats` function. |
| 462 | |
| 463 | .. versionadded:: 3.2 |
| 464 | |
| 465 | |
| 466 | .. function:: unregister_unpack_format(name) |
| 467 | |
| 468 | Unregister an unpack format. *name* is the name of the format. |
| 469 | |
| 470 | .. versionadded:: 3.2 |
| 471 | |
| 472 | |
| 473 | .. function:: get_unpack_formats() |
| 474 | |
| 475 | Return a list of all registered formats for unpacking. |
| 476 | Each element of the returned sequence is a tuple |
| 477 | ``(name, extensions, description)``. |
| 478 | |
| 479 | By default :mod:`shutil` provides these formats: |
| 480 | |
| 481 | - *gztar*: gzip'ed tar-file |
Tarek Ziadé | ffa155a | 2010-04-29 13:34:35 +0000 | [diff] [blame] | 482 | - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available.) |
Tarek Ziadé | 6ac9172 | 2010-04-28 17:51:36 +0000 | [diff] [blame] | 483 | - *tar*: uncompressed tar file |
| 484 | - *zip*: ZIP file |
| 485 | |
| 486 | You can register new formats or provide your own unpacker for any existing |
| 487 | formats, by using :func:`register_unpack_format`. |
| 488 | |
| 489 | .. versionadded:: 3.2 |
| 490 | |
| 491 | |
Éric Araujo | f2fbb9c | 2012-01-16 16:55:55 +0100 | [diff] [blame] | 492 | .. _shutil-archiving-example: |
Tarek Ziadé | 6ac9172 | 2010-04-28 17:51:36 +0000 | [diff] [blame] | 493 | |
Tarek Ziadé | 396fad7 | 2010-02-23 05:30:31 +0000 | [diff] [blame] | 494 | Archiving example |
| 495 | ::::::::::::::::: |
| 496 | |
| 497 | In this example, we create a gzip'ed tar-file archive containing all files |
| 498 | found in the :file:`.ssh` directory of the user:: |
| 499 | |
| 500 | >>> from shutil import make_archive |
| 501 | >>> import os |
| 502 | >>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive')) |
| 503 | >>> root_dir = os.path.expanduser(os.path.join('~', '.ssh')) |
| 504 | >>> make_archive(archive_name, 'gztar', root_dir) |
| 505 | '/Users/tarek/myarchive.tar.gz' |
| 506 | |
| 507 | The resulting archive contains:: |
| 508 | |
| 509 | $ tar -tzvf /Users/tarek/myarchive.tar.gz |
| 510 | drwx------ tarek/staff 0 2010-02-01 16:23:40 ./ |
| 511 | -rw-r--r-- tarek/staff 609 2008-06-09 13:26:54 ./authorized_keys |
| 512 | -rwxr-xr-x tarek/staff 65 2008-06-09 13:26:54 ./config |
| 513 | -rwx------ tarek/staff 668 2008-06-09 13:26:54 ./id_dsa |
| 514 | -rwxr-xr-x tarek/staff 609 2008-06-09 13:26:54 ./id_dsa.pub |
| 515 | -rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa |
| 516 | -rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub |
| 517 | -rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts |
Antoine Pitrou | bcf2b59 | 2012-02-08 23:28:36 +0100 | [diff] [blame] | 518 | |
| 519 | |
| 520 | Querying the size of the output terminal |
| 521 | ---------------------------------------- |
| 522 | |
| 523 | .. versionadded:: 3.3 |
| 524 | |
| 525 | .. function:: get_terminal_size(fallback=(columns, lines)) |
| 526 | |
| 527 | Get the size of the terminal window. |
| 528 | |
| 529 | For each of the two dimensions, the environment variable, ``COLUMNS`` |
| 530 | and ``LINES`` respectively, is checked. If the variable is defined and |
| 531 | the value is a positive integer, it is used. |
| 532 | |
| 533 | When ``COLUMNS`` or ``LINES`` is not defined, which is the common case, |
| 534 | the terminal connected to :data:`sys.__stdout__` is queried |
| 535 | by invoking :func:`os.get_terminal_size`. |
| 536 | |
| 537 | If the terminal size cannot be successfully queried, either because |
| 538 | the system doesn't support querying, or because we are not |
| 539 | connected to a terminal, the value given in ``fallback`` parameter |
| 540 | is used. ``fallback`` defaults to ``(80, 24)`` which is the default |
| 541 | size used by many terminal emulators. |
| 542 | |
| 543 | The value returned is a named tuple of type :class:`os.terminal_size`. |
| 544 | |
| 545 | See also: The Single UNIX Specification, Version 2, |
| 546 | `Other Environment Variables`_. |
| 547 | |
| 548 | .. _`Other Environment Variables`: |
| 549 | http://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html#tag_002_003 |
| 550 | |