Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 1 | \section{\module{shutil} --- |
Fred Drake | dbd72a4 | 1999-02-01 21:27:59 +0000 | [diff] [blame] | 2 | High-level file operations} |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 3 | |
| 4 | \declaremodule{standard}{shutil} |
Fred Drake | dbd72a4 | 1999-02-01 21:27:59 +0000 | [diff] [blame] | 5 | \modulesynopsis{High-level file operations, including copying.} |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 6 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 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. |
Fred Drake | 94c4a79 | 1998-12-28 21:58:57 +0000 | [diff] [blame] | 13 | \index{file!copying} |
| 14 | \index{copying files} |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 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} |
Fred Drake | 043d5e5 | 2001-03-02 16:46:42 +0000 | [diff] [blame] | 22 | Copy the contents of the file named \var{src} to a file named |
Andrew M. Kuchling | 99872c1 | 2004-05-05 17:21:51 +0000 | [diff] [blame] | 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 |
Fred Drake | 757f780 | 2001-09-04 18:26:27 +0000 | [diff] [blame] | 28 | \var{dst} are path names given as strings. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 29 | \end{funcdesc} |
| 30 | |
Fred Drake | 578a3f9 | 2000-07-31 15:45:46 +0000 | [diff] [blame] | 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 | |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 40 | \begin{funcdesc}{copymode}{src, dst} |
| 41 | Copy the permission bits from \var{src} to \var{dst}. The file |
Fred Drake | 757f780 | 2001-09-04 18:26:27 +0000 | [diff] [blame] | 42 | contents, owner, and group are unaffected. \var{src} and \var{dst} |
| 43 | are path names given as strings. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 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 |
Fred Drake | 757f780 | 2001-09-04 18:26:27 +0000 | [diff] [blame] | 49 | group are unaffected. \var{src} and \var{dst} are path names given |
| 50 | as strings. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 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 |
Fred Drake | 757f780 | 2001-09-04 18:26:27 +0000 | [diff] [blame] | 57 | bits are copied. \var{src} and \var{dst} are path names given as |
| 58 | strings. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 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 |
Fred Drake | d290c10 | 1999-11-09 18:03:00 +0000 | [diff] [blame] | 64 | \UNIX{} command \program{cp} \programopt{-p}. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 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. Individual files are copied using |
| 71 | \function{copy2()}. If \var{symlinks} is true, symbolic links in |
| 72 | the source tree are represented as symbolic links in the new tree; |
| 73 | if false or omitted, the contents of the linked files are copied to |
Neal Norwitz | 7aba3d4 | 2003-02-23 21:36:47 +0000 | [diff] [blame] | 74 | the new tree. If exception(s) occur, an Error is raised |
| 75 | with a list of reasons. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 76 | |
| 77 | The source code for this should be considered an example rather than |
| 78 | a tool. |
Neal Norwitz | 7aba3d4 | 2003-02-23 21:36:47 +0000 | [diff] [blame] | 79 | \versionchanged[Error is raised if any exceptions occur during copying, |
| 80 | rather than printing a message]{2.3} |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 81 | \end{funcdesc} |
| 82 | |
| 83 | \begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}} |
Barry Warsaw | 6d9f9b3 | 2003-01-24 17:33:30 +0000 | [diff] [blame] | 84 | Delete an entire directory tree.\index{directory!deleting} |
| 85 | If \var{ignore_errors} is true, |
Fred Drake | 28bdc62 | 2002-06-18 14:31:04 +0000 | [diff] [blame] | 86 | errors resulting from failed removals will be ignored; if false or |
| 87 | omitted, such errors are handled by calling a handler specified by |
| 88 | \var{onerror} or, if that is omitted, they raise an exception. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 89 | |
| 90 | If \var{onerror} is provided, it must be a callable that accepts |
| 91 | three parameters: \var{function}, \var{path}, and \var{excinfo}. |
| 92 | The first parameter, \var{function}, is the function which raised |
| 93 | the exception; it will be \function{os.remove()} or |
| 94 | \function{os.rmdir()}. The second parameter, \var{path}, will be |
| 95 | the path name passed to \var{function}. The third parameter, |
| 96 | \var{excinfo}, will be the exception information return by |
| 97 | \function{sys.exc_info()}. Exceptions raised by \var{onerror} will |
| 98 | not be caught. |
| 99 | \end{funcdesc} |
| 100 | |
Martin v. Löwis | e9ce0b0 | 2002-10-07 13:23:24 +0000 | [diff] [blame] | 101 | \begin{funcdesc}{move}{src, dst} |
| 102 | Recursively move a file or directory to another location. |
| 103 | |
| 104 | If the destination is on our current filesystem, then simply use |
| 105 | rename. Otherwise, copy src to the dst and then remove src. |
| 106 | |
| 107 | \versionadded{2.3} |
| 108 | \end{funcdesc} |
| 109 | |
| 110 | \begin{excdesc}{Error} |
| 111 | This exception collects exceptions that raised during a mult-file |
| 112 | operation. For \function{copytree}, the exception argument is a |
| 113 | list of 3-tuples (\var{srcname}, \var{dstname}, \var{exception}). |
| 114 | |
| 115 | \versionadded{2.3} |
| 116 | \end{excdesc} |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 117 | |
| 118 | \subsection{Example \label{shutil-example}} |
| 119 | |
| 120 | This example is the implementation of the \function{copytree()} |
Fred Drake | 11bc8cf | 1999-04-21 17:08:51 +0000 | [diff] [blame] | 121 | function, described above, with the docstring omitted. It |
| 122 | demonstrates many of the other functions provided by this module. |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 123 | |
| 124 | \begin{verbatim} |
| 125 | def copytree(src, dst, symlinks=0): |
| 126 | names = os.listdir(src) |
| 127 | os.mkdir(dst) |
| 128 | for name in names: |
| 129 | srcname = os.path.join(src, name) |
| 130 | dstname = os.path.join(dst, name) |
| 131 | try: |
| 132 | if symlinks and os.path.islink(srcname): |
| 133 | linkto = os.readlink(srcname) |
| 134 | os.symlink(linkto, dstname) |
| 135 | elif os.path.isdir(srcname): |
Raymond Hettinger | 550fd5d | 2002-06-30 04:43:20 +0000 | [diff] [blame] | 136 | copytree(srcname, dstname, symlinks) |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 137 | else: |
| 138 | copy2(srcname, dstname) |
Fred Drake | 449e18f | 1998-12-28 20:16:58 +0000 | [diff] [blame] | 139 | except (IOError, os.error), why: |
| 140 | print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why)) |
| 141 | \end{verbatim} |