Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libshutil.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents cfc5e5160cf5
children a44f3877a386
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{shutil} ---
10065
6abd84aab08a Added module synopsis.
Fred Drake <fdrake@acm.org>
parents: 9737
diff changeset
2 High-level file operations}
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{shutil}
10065
6abd84aab08a Added module synopsis.
Fred Drake <fdrake@acm.org>
parents: 9737
diff changeset
5 \modulesynopsis{High-level file operations, including copying.}
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7 % partly based on the docstrings
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 The \module{shutil} module offers a number of high-level operations on
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 files and collections of files. In particular, functions are provided
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 which support file copying and removal.
9737
3415d13f8bc8 Added index entries to make it easier to locate directory & file operations.
Fred Drake <fdrake@acm.org>
parents: 9731
diff changeset
13 \index{file!copying}
3415d13f8bc8 Added index entries to make it easier to locate directory & file operations.
Fred Drake <fdrake@acm.org>
parents: 9731
diff changeset
14 \index{copying files}
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 \strong{Caveat:} On MacOS, the resource fork and other metadata are
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 not used. For file copies, this means that resources will be lost and
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 file type and creator codes will not be correct.
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 \begin{funcdesc}{copyfile}{src, dst}
16963
2c290d4c3b38 For copyfile(), be explicit that src and dst are file names; that was only
Fred Drake <fdrake@acm.org>
parents: 13762
diff changeset
22 Copy the contents of the file named \var{src} to a file named
2c290d4c3b38 For copyfile(), be explicit that src and dst are file names; that was only
Fred Drake <fdrake@acm.org>
parents: 13762
diff changeset
23 \var{dst}. If \var{dst} exists, it will be replaced, otherwise it
19689
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
24 will be created. Special files such as character or block devices
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
25 and pipes cannot not be copied with this function. \var{src} and
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
26 \var{dst} are path names given as strings.
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 \end{funcdesc}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28
13762
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
29 \begin{funcdesc}{copyfileobj}{fsrc, fdst\optional{, length}}
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
30 Copy the contents of the file-like object \var{fsrc} to the
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
31 file-like object \var{fdst}. The integer \var{length}, if given,
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
32 is the buffer size. In particular, a negative \var{length} value
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
33 means to copy the data without looping over the source data in
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
34 chunks; by default the data is read in chunks to avoid uncontrolled
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
35 memory consumption.
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
36 \end{funcdesc}
2d00bced6038 Moshe Zadka <mzadka@geocities.com>:
Fred Drake <fdrake@acm.org>
parents: 11454
diff changeset
37
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 \begin{funcdesc}{copymode}{src, dst}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 Copy the permission bits from \var{src} to \var{dst}. The file
19689
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
40 contents, owner, and group are unaffected. \var{src} and \var{dst}
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
41 are path names given as strings.
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 \end{funcdesc}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 \begin{funcdesc}{copystat}{src, dst}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 Copy the permission bits, last access time, and last modification
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 time from \var{src} to \var{dst}. The file contents, owner, and
19689
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
47 group are unaffected. \var{src} and \var{dst} are path names given
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
48 as strings.
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 \end{funcdesc}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 \begin{funcdesc}{copy}{src, dst}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 Copy the file \var{src} to the file or directory \var{dst}. If
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 \var{dst} is a directory, a file with the same basename as \var{src}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 is created (or overwritten) in the directory specified. Permission
19689
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
55 bits are copied. \var{src} and \var{dst} are path names given as
cfc5e5160cf5 Add more detail to the descriptions of the shutil functions.
Fred Drake <fdrake@acm.org>
parents: 16963
diff changeset
56 strings.
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57 \end{funcdesc}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 \begin{funcdesc}{copy2}{src, dst}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 Similar to \function{copy()}, but last access time and last
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 modification time are copied as well. This is similar to the
11454
e74ef2b50555 Use \programopt in one place.
Fred Drake <fdrake@acm.org>
parents: 10653
diff changeset
62 \UNIX{} command \program{cp} \programopt{-p}.
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 \end{funcdesc}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 \begin{funcdesc}{copytree}{src, dst\optional{, symlinks}}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 Recursively copy an entire directory tree rooted at \var{src}. The
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 destination directory, named by \var{dst}, must not already exist;
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 it will be created. Individual files are copied using
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 \function{copy2()}. If \var{symlinks} is true, symbolic links in
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 the source tree are represented as symbolic links in the new tree;
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 if false or omitted, the contents of the linked files are copied to
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 the new tree. Errors are reported to standard output.
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 The source code for this should be considered an example rather than
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 a tool.
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 \end{funcdesc}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 \begin{funcdesc}{rmtree}{path\optional{, ignore_errors\optional{, onerror}}}
9737
3415d13f8bc8 Added index entries to make it easier to locate directory & file operations.
Fred Drake <fdrake@acm.org>
parents: 9731
diff changeset
79 \index{directory!deleting}
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 Delete an entire directory tree. If \var{ignore_errors} is true,
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 errors will be ignored; if false or omitted, errors are handled by
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 calling a handler specified by \var{onerror} or raise an exception.
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 If \var{onerror} is provided, it must be a callable that accepts
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 three parameters: \var{function}, \var{path}, and \var{excinfo}.
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 The first parameter, \var{function}, is the function which raised
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 the exception; it will be \function{os.remove()} or
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 \function{os.rmdir()}. The second parameter, \var{path}, will be
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 the path name passed to \var{function}. The third parameter,
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 \var{excinfo}, will be the exception information return by
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 \function{sys.exc_info()}. Exceptions raised by \var{onerror} will
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 not be caught.
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 \end{funcdesc}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 \subsection{Example \label{shutil-example}}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98 This example is the implementation of the \function{copytree()}
10653
42dbfd498387 Explain *why* the copytree() implementation is presented as the
Fred Drake <fdrake@acm.org>
parents: 10065
diff changeset
99 function, described above, with the docstring omitted. It
42dbfd498387 Explain *why* the copytree() implementation is presented as the
Fred Drake <fdrake@acm.org>
parents: 10065
diff changeset
100 demonstrates many of the other functions provided by this module.
9731
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102 \begin{verbatim}
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 def copytree(src, dst, symlinks=0):
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 names = os.listdir(src)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105 os.mkdir(dst)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 for name in names:
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 srcname = os.path.join(src, name)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 dstname = os.path.join(dst, name)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 try:
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 if symlinks and os.path.islink(srcname):
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 linkto = os.readlink(srcname)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112 os.symlink(linkto, dstname)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 elif os.path.isdir(srcname):
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 copytree(srcname, dstname)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 else:
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 copy2(srcname, dstname)
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 # XXX What about devices, sockets etc.?
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 except (IOError, os.error), why:
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 print "Can't copy %s to %s: %s" % (`srcname`, `dstname`, str(why))
72f50636dfea Add documentation for shutil module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \end{verbatim}