← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/shutil.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
 
 
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
 
16
copying 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.
 
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
 
 
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
 
 
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`.
 
79
 
 
80
 
 
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
   .. versionadded:: 2.6
 
88
 
 
89
 
 
90
.. function:: copytree(src, dst[, symlinks=False[, ignore=None]])
 
91
 
 
92
   Recursively copy an entire directory tree rooted at *src*.  The destination
 
93
   directory, named by *dst*, must not already exist; it will be created as well
 
94
   as missing parent directories.  Permissions and times of directories are
 
95
   copied with :func:`copystat`, individual files are copied using
 
96
   :func:`copy2`.
 
97
 
 
98
   If *symlinks* is true, symbolic links in the source tree are represented as
 
99
   symbolic links in the new tree; if false or omitted, the contents of the
 
100
   linked files are copied to the new tree.
 
101
 
 
102
   If *ignore* is given, it must be a callable that will receive as its
 
103
   arguments the directory being visited by :func:`copytree`, and a list of its
 
104
   contents, as returned by :func:`os.listdir`.  Since :func:`copytree` is
 
105
   called recursively, the *ignore* callable will be called once for each
 
106
   directory that is copied.  The callable must return a sequence of directory
 
107
   and file names relative to the current directory (i.e. a subset of the items
 
108
   in its second argument); these names will then be ignored in the copy
 
109
   process.  :func:`ignore_patterns` can be used to create such a callable that
 
110
   ignores names based on glob-style patterns.
 
111
 
 
112
   If exception(s) occur, an :exc:`Error` is raised with a list of reasons.
 
113
 
 
114
   The source code for this should be considered an example rather than the
 
115
   ultimate tool.
 
116
 
 
117
   .. versionchanged:: 2.3
 
118
      :exc:`Error` is raised if any exceptions occur during copying, rather than
 
119
      printing a message.
 
120
 
 
121
   .. versionchanged:: 2.5
 
122
      Create intermediate directories needed to create *dst*, rather than raising an
 
123
      error. Copy permissions and times of directories using :func:`copystat`.
 
124
 
 
125
   .. versionchanged:: 2.6
 
126
      Added the *ignore* argument to be able to influence what is being copied. 
 
127
 
 
128
 
 
129
.. function:: rmtree(path[, ignore_errors[, onerror]])
 
130
 
 
131
   .. index:: single: directory; deleting
 
132
 
 
133
   Delete an entire directory tree; *path* must point to a directory (but not a
 
134
   symbolic link to a directory).  If *ignore_errors* is true, errors resulting
 
135
   from failed removals will be ignored; if false or omitted, such errors are
 
136
   handled by calling a handler specified by *onerror* or, if that is omitted,
 
137
   they raise an exception.
 
138
 
 
139
   If *onerror* is provided, it must be a callable that accepts three
 
140
   parameters: *function*, *path*, and *excinfo*. The first parameter,
 
141
   *function*, is the function which raised the exception; it will be
 
142
   :func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or
 
143
   :func:`os.rmdir`.  The second parameter, *path*, will be the path name passed
 
144
   to *function*.  The third parameter, *excinfo*, will be the exception
 
145
   information return by :func:`sys.exc_info`.  Exceptions raised by *onerror*
 
146
   will not be caught.
 
147
 
 
148
   .. versionchanged:: 2.6
 
149
      Explicitly check for *path* being a symbolic link and raise :exc:`OSError`
 
150
      in that case.
 
151
 
 
152
 
 
153
.. function:: move(src, dst)
 
154
 
 
155
   Recursively move a file or directory to another location.
 
156
 
 
157
   If the destination is on the current filesystem, then simply use rename.
 
158
   Otherwise, copy src to the dst and then remove src.
 
159
 
 
160
   .. versionadded:: 2.3
 
161
 
 
162
 
 
163
.. exception:: Error
 
164
 
 
165
   This exception collects exceptions that raised during a multi-file operation. For
 
166
   :func:`copytree`, the exception argument is a list of 3-tuples (*srcname*,
 
167
   *dstname*, *exception*).
 
168
 
 
169
   .. versionadded:: 2.3
 
170
 
 
171
 
 
172
.. _shutil-example:
 
173
 
 
174
Example
 
175
-------
 
176
 
 
177
This example is the implementation of the :func:`copytree` function, described
 
178
above, with the docstring omitted.  It demonstrates many of the other functions
 
179
provided by this module. ::
 
180
 
 
181
   def copytree(src, dst, symlinks=False, ignore=None):
 
182
       names = os.listdir(src)
 
183
       if ignore is not None:
 
184
           ignored_names = ignore(src, names)
 
185
       else:
 
186
           ignored_names = set()
 
187
 
 
188
       os.makedirs(dst)
 
189
       errors = []
 
190
       for name in names:
 
191
           if name in ignored_names:   
 
192
               continue
 
193
           srcname = os.path.join(src, name)
 
194
           dstname = os.path.join(dst, name)
 
195
           try:
 
196
               if symlinks and os.path.islink(srcname):
 
197
                   linkto = os.readlink(srcname)
 
198
                   os.symlink(linkto, dstname)
 
199
               elif os.path.isdir(srcname):
 
200
                   copytree(srcname, dstname, symlinks, ignore)
 
201
               else:
 
202
                   copy2(srcname, dstname)
 
203
               # XXX What about devices, sockets etc.?
 
204
           except (IOError, os.error), why:
 
205
               errors.append((srcname, dstname, str(why)))
 
206
           # catch the Error from the recursive copytree so that we can
 
207
           # continue with other files
 
208
           except Error, err:
 
209
               errors.extend(err.args[0])
 
210
       try:
 
211
           copystat(src, dst)
 
212
       except WindowsError:
 
213
           # can't copy file access times on Windows
 
214
           pass
 
215
       except OSError, why:
 
216
           errors.extend((src, dst, str(why)))
 
217
       if errors:
 
218
           raise Error, errors
 
219
 
 
220
Another example that uses the :func:`ignore_patterns` helper::
 
221
 
 
222
   from shutil import copytree, ignore_patterns
 
223
   
 
224
   copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))
 
225
 
 
226
This will copy everything except ``.pyc`` files and files or directories whose
 
227
name starts with ``tmp``.
 
228
 
 
229
Another example that uses the *ignore* argument to add a logging call::
 
230
 
 
231
   from shutil import copytree
 
232
   import logging
 
233
   
 
234
   def _logpath(path, names):
 
235
       logging.info('Working in %s' % path)
 
236
       return []   # nothing will be ignored
 
237
 
 
238
   copytree(source, destination, ignore=_logpath)
 
239