/Doc/library/shutil.rst

  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