| 1 | \section{\module{shutil} ---
|
|---|
| 2 | High-level file operations}
|
|---|
| 3 |
|
|---|
| 4 | \declaremodule{standard}{shutil}
|
|---|
| 5 | \modulesynopsis{High-level file operations, including copying.}
|
|---|
| 6 | \sectionauthor{Fred L. Drake, Jr.}{[email protected]}
|
|---|
| 7 | % partly based on the docstrings
|
|---|
| 8 |
|
|---|
| 9 |
|
|---|
| 10 | The \module{shutil} module offers a number of high-level operations on
|
|---|
| 11 | files and collections of files. In particular, functions are provided
|
|---|
| 12 | which support file copying and removal.
|
|---|
| 13 | \index{file!copying}
|
|---|
| 14 | \index{copying files}
|
|---|
| 15 |
|
|---|
| 16 | \strong{Caveat:} On MacOS, the resource fork and other metadata are
|
|---|
| 17 | not used. For file copies, this means that resources will be lost and
|
|---|
| 18 | file type and creator codes will not be correct.
|
|---|
| 19 |
|
|---|
| 20 |
|
|---|
| 21 | \begin{funcdesc}{copyfile}{src, dst}
|
|---|
| 22 | Copy the contents of the file named \var{src} to a file named
|
|---|
| 23 | \var{dst}. The destination location must be writable; otherwise,
|
|---|
| 24 | an \exception{IOError} exception will be raised.
|
|---|
| 25 | If \var{dst} already exists, it will be replaced.
|
|---|
| 26 | Special files such as character or block devices
|
|---|
| 27 | and pipes cannot be copied with this function. \var{src} and
|
|---|
| 28 | \var{dst} are path names given as strings.
|
|---|
| 29 | \end{funcdesc}
|
|---|
| 30 |
|
|---|
| 31 | \begin{funcdesc}{copyfileobj}{fsrc, fdst\optional{, length}}
|
|---|
| 32 | Copy the contents of the file-like object \var{fsrc} to the
|
|---|
| 33 | file-like object \var{fdst}. The integer \var{length}, if given,
|
|---|
| 34 | is the buffer size. In particular, a negative \var{length} value
|
|---|
| 35 | 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
|
|---|
| 37 | memory consumption.
|
|---|
| 38 | \end{funcdesc}
|
|---|
| 39 |
|
|---|
| 40 | \begin{funcdesc}{copymode}{src, dst}
|
|---|
| 41 | Copy the permission bits from \var{src} to \var{dst}. The file
|
|---|
| 42 | contents, owner, and group are unaffected. \var{src} and \var{dst}
|
|---|
| 43 | are path names given as strings.
|
|---|
| 44 | \end{funcdesc}
|
|---|
| 45 |
|
|---|
| 46 | \begin{funcdesc}{copystat}{src, dst}
|
|---|
| 47 | Copy the permission bits, last access time, and last modification
|
|---|
| 48 | time from \var{src} to \var{dst}. The file contents, owner, and
|
|---|
| 49 | group are unaffected. \var{src} and \var{dst} are path names given
|
|---|
| 50 | as strings.
|
|---|
| 51 | \end{funcdesc}
|
|---|
| 52 |
|
|---|
| 53 | \begin{funcdesc}{copy}{src, dst}
|
|---|
| 54 | Copy the file \var{src} to the file or directory \var{dst}. If
|
|---|
| 55 | \var{dst} is a directory, a file with the same basename as \var{src}
|
|---|
| 56 | is created (or overwritten) in the directory specified. Permission
|
|---|
| 57 | bits are copied. \var{src} and \var{dst} are path names given as
|
|---|
| 58 | strings.
|
|---|
| 59 | \end{funcdesc}
|
|---|
| 60 |
|
|---|
| 61 | \begin{funcdesc}{copy2}{src, dst}
|
|---|
| 62 | Similar to \function{copy()}, but last access time and last
|
|---|
| 63 | modification time are copied as well. This is similar to the
|
|---|
| 64 | \UNIX{} command \program{cp} \programopt{-p}.
|
|---|
| 65 | \end{funcdesc}
|
|---|
| 66 |
|
|---|
| 67 | \begin{funcdesc}{copytree}{src, dst\optional{, symlinks}}
|
|---|
| 68 | Recursively copy an entire directory tree rooted at \var{src}. The
|
|---|
| 69 | destination directory, named by \var{dst}, must not already exist;
|
|---|
| 70 | it will be created as well as missing parent directories.
|
|---|
| 71 | Permissions and times of directories are copied with \function{copystat()},
|
|---|
| 72 | individual files are copied using \function{copy2()}.
|
|---|
| 73 | If \var{symlinks} is true, symbolic links in
|
|---|
| 74 | the source tree are represented as symbolic links in the new tree;
|
|---|
| 75 | if false or omitted, the contents of the linked files are copied to
|
|---|
| 76 | the new tree. If exception(s) occur, an \exception{Error} is raised
|
|---|
| 77 | with a list of reasons.
|
|---|
| 78 |
|
|---|
| 79 | The source code for this should be considered an example rather than
|
|---|
| 80 | a tool.
|
|---|
| 81 |
|
|---|
| 82 | \versionchanged[\exception{Error} is raised if any exceptions occur during
|
|---|
| 83 | copying, rather than printing a message]{2.3}
|
|---|
| 84 |
|
|---|
| 85 | \versionchanged[Create intermediate directories needed to create \var{dst},
|
|---|
| 86 | rather than raising an error. Copy permissions and times of
|
|---|
| 87 | directories using \function{copystat()}]{2.5}
|
|---|
| 88 |
|
|---|
| 89 | \end{funcdesc}
|
|---|
| 90 |
|
|---|
| 91 | \begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
|
|---|
| 92 | Delete an entire directory tree.\index{directory!deleting}
|
|---|
| 93 | If \var{ignore_errors} is true,
|
|---|
| 94 | errors resulting from failed removals will be ignored; if false or
|
|---|
| 95 | omitted, such errors are handled by calling a handler specified by
|
|---|
| 96 | \var{onerror} or, if that is omitted, they raise an exception.
|
|---|
| 97 |
|
|---|
| 98 | If \var{onerror} is provided, it must be a callable that accepts
|
|---|
| 99 | three parameters: \var{function}, \var{path}, and \var{excinfo}.
|
|---|
| 100 | The first parameter, \var{function}, is the function which raised
|
|---|
| 101 | the exception; it will be \function{os.listdir()}, \function{os.remove()} or
|
|---|
| 102 | \function{os.rmdir()}. The second parameter, \var{path}, will be
|
|---|
| 103 | the path name passed to \var{function}. The third parameter,
|
|---|
| 104 | \var{excinfo}, will be the exception information return by
|
|---|
| 105 | \function{sys.exc_info()}. Exceptions raised by \var{onerror} will
|
|---|
| 106 | not be caught.
|
|---|
| 107 | \end{funcdesc}
|
|---|
| 108 |
|
|---|
| 109 | \begin{funcdesc}{move}{src, dst}
|
|---|
| 110 | Recursively move a file or directory to another location.
|
|---|
| 111 |
|
|---|
| 112 | If the destination is on our current filesystem, then simply use
|
|---|
| 113 | rename. Otherwise, copy src to the dst and then remove src.
|
|---|
| 114 |
|
|---|
| 115 | \versionadded{2.3}
|
|---|
| 116 | \end{funcdesc}
|
|---|
| 117 |
|
|---|
| 118 | \begin{excdesc}{Error}
|
|---|
| 119 | This exception collects exceptions that raised during a mult-file
|
|---|
| 120 | operation. For \function{copytree}, the exception argument is a
|
|---|
| 121 | list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}).
|
|---|
| 122 |
|
|---|
| 123 | \versionadded{2.3}
|
|---|
| 124 | \end{excdesc}
|
|---|
| 125 |
|
|---|
| 126 | \subsection{Example \label{shutil-example}}
|
|---|
| 127 |
|
|---|
| 128 | This example is the implementation of the \function{copytree()}
|
|---|
| 129 | function, described above, with the docstring omitted. It
|
|---|
| 130 | demonstrates many of the other functions provided by this module.
|
|---|
| 131 |
|
|---|
| 132 | \begin{verbatim}
|
|---|
| 133 | def copytree(src, dst, symlinks=0):
|
|---|
| 134 | names = os.listdir(src)
|
|---|
| 135 | os.mkdir(dst)
|
|---|
| 136 | for name in names:
|
|---|
| 137 | srcname = os.path.join(src, name)
|
|---|
| 138 | dstname = os.path.join(dst, name)
|
|---|
| 139 | try:
|
|---|
| 140 | if symlinks and os.path.islink(srcname):
|
|---|
| 141 | linkto = os.readlink(srcname)
|
|---|
| 142 | os.symlink(linkto, dstname)
|
|---|
| 143 | elif os.path.isdir(srcname):
|
|---|
| 144 | copytree(srcname, dstname, symlinks)
|
|---|
| 145 | else:
|
|---|
| 146 | copy2(srcname, dstname)
|
|---|
| 147 | except (IOError, os.error), why:
|
|---|
| 148 | print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
|
|---|
| 149 | \end{verbatim}
|
|---|
