1"""distutils.dir_util 2 3Utility functions for manipulating directories and directory trees.""" 4 5__revision__ = "$Id$" 6 7import os 8import errno 9from distutils.errors import DistutilsFileError, DistutilsInternalError 10from distutils import log 11 12# cache for by mkpath() -- in addition to cheapening redundant calls, 13# eliminates redundant "creating /foo/bar/baz" messages in dry-run mode 14_path_created = {} 15 16# I don't use os.makedirs because a) it's new to Python 1.5.2, and 17# b) it blows up if the directory already exists (I want to silently 18# succeed in that case). 19def mkpath(name, mode=0777, verbose=1, dry_run=0): 20 """Create a directory and any missing ancestor directories. 21 22 If the directory already exists (or if 'name' is the empty string, which 23 means the current directory, which of course exists), then do nothing. 24 Raise DistutilsFileError if unable to create some directory along the way 25 (eg. some sub-path exists, but is a file rather than a directory). 26 If 'verbose' is true, print a one-line summary of each mkdir to stdout. 27 Return the list of directories actually created. 28 """ 29 30 global _path_created 31 32 # Detect a common bug -- name is None 33 if not isinstance(name, basestring): 34 raise DistutilsInternalError, \ 35 "mkpath: 'name' must be a string (got %r)" % (name,) 36 37 # XXX what's the better way to handle verbosity? print as we create 38 # each directory in the path (the current behaviour), or only announce 39 # the creation of the whole path? (quite easy to do the latter since 40 # we're not using a recursive algorithm) 41 42 name = os.path.normpath(name) 43 created_dirs = [] 44 if os.path.isdir(name) or name == '': 45 return created_dirs 46 if _path_created.get(os.path.abspath(name)): 47 return created_dirs 48 49 (head, tail) = os.path.split(name) 50 tails = [tail] # stack of lone dirs to create 51 52 while head and tail and not os.path.isdir(head): 53 (head, tail) = os.path.split(head) 54 tails.insert(0, tail) # push next higher dir onto stack 55 56 # now 'head' contains the deepest directory that already exists 57 # (that is, the child of 'head' in 'name' is the highest directory 58 # that does *not* exist) 59 for d in tails: 60 #print "head = %s, d = %s: " % (head, d), 61 head = os.path.join(head, d) 62 abs_head = os.path.abspath(head) 63 64 if _path_created.get(abs_head): 65 continue 66 67 if verbose >= 1: 68 log.info("creating %s", head) 69 70 if not dry_run: 71 try: 72 os.mkdir(head, mode) 73 except OSError, exc: 74 if not (exc.errno == errno.EEXIST and os.path.isdir(head)): 75 raise DistutilsFileError( 76 "could not create '%s': %s" % (head, exc.args[-1])) 77 created_dirs.append(head) 78 79 _path_created[abs_head] = 1 80 return created_dirs 81 82def create_tree(base_dir, files, mode=0777, verbose=1, dry_run=0): 83 """Create all the empty directories under 'base_dir' needed to put 'files' 84 there. 85 86 'base_dir' is just the a name of a directory which doesn't necessarily 87 exist yet; 'files' is a list of filenames to be interpreted relative to 88 'base_dir'. 'base_dir' + the directory portion of every file in 'files' 89 will be created if it doesn't already exist. 'mode', 'verbose' and 90 'dry_run' flags are as for 'mkpath()'. 91 """ 92 # First get the list of directories to create 93 need_dir = {} 94 for file in files: 95 need_dir[os.path.join(base_dir, os.path.dirname(file))] = 1 96 need_dirs = need_dir.keys() 97 need_dirs.sort() 98 99 # Now create them 100 for dir in need_dirs: 101 mkpath(dir, mode, verbose=verbose, dry_run=dry_run) 102 103def copy_tree(src, dst, preserve_mode=1, preserve_times=1, 104 preserve_symlinks=0, update=0, verbose=1, dry_run=0): 105 """Copy an entire directory tree 'src' to a new location 'dst'. 106 107 Both 'src' and 'dst' must be directory names. If 'src' is not a 108 directory, raise DistutilsFileError. If 'dst' does not exist, it is 109 created with 'mkpath()'. The end result of the copy is that every 110 file in 'src' is copied to 'dst', and directories under 'src' are 111 recursively copied to 'dst'. Return the list of files that were 112 copied or might have been copied, using their output name. The 113 return value is unaffected by 'update' or 'dry_run': it is simply 114 the list of all files under 'src', with the names changed to be 115 under 'dst'. 116 117 'preserve_mode' and 'preserve_times' are the same as for 118 'copy_file'; note that they only apply to regular files, not to 119 directories. If 'preserve_symlinks' is true, symlinks will be 120 copied as symlinks (on platforms that support them!); otherwise 121 (the default), the destination of the symlink will be copied. 122 'update' and 'verbose' are the same as for 'copy_file'. 123 """ 124 from distutils.file_util import copy_file 125 126 if not dry_run and not os.path.isdir(src): 127 raise DistutilsFileError, \ 128 "cannot copy tree '%s': not a directory" % src 129 try: 130 names = os.listdir(src) 131 except os.error, (errno, errstr): 132 if dry_run: 133 names = [] 134 else: 135 raise DistutilsFileError, \ 136 "error listing files in '%s': %s" % (src, errstr) 137 138 if not dry_run: 139 mkpath(dst, verbose=verbose) 140 141 outputs = [] 142 143 for n in names: 144 src_name = os.path.join(src, n) 145 dst_name = os.path.join(dst, n) 146 147 if preserve_symlinks and os.path.islink(src_name): 148 link_dest = os.readlink(src_name) 149 if verbose >= 1: 150 log.info("linking %s -> %s", dst_name, link_dest) 151 if not dry_run: 152 os.symlink(link_dest, dst_name) 153 outputs.append(dst_name) 154 155 elif os.path.isdir(src_name): 156 outputs.extend( 157 copy_tree(src_name, dst_name, preserve_mode, 158 preserve_times, preserve_symlinks, update, 159 verbose=verbose, dry_run=dry_run)) 160 else: 161 copy_file(src_name, dst_name, preserve_mode, 162 preserve_times, update, verbose=verbose, 163 dry_run=dry_run) 164 outputs.append(dst_name) 165 166 return outputs 167 168def _build_cmdtuple(path, cmdtuples): 169 """Helper for remove_tree().""" 170 for f in os.listdir(path): 171 real_f = os.path.join(path,f) 172 if os.path.isdir(real_f) and not os.path.islink(real_f): 173 _build_cmdtuple(real_f, cmdtuples) 174 else: 175 cmdtuples.append((os.remove, real_f)) 176 cmdtuples.append((os.rmdir, path)) 177 178def remove_tree(directory, verbose=1, dry_run=0): 179 """Recursively remove an entire directory tree. 180 181 Any errors are ignored (apart from being reported to stdout if 'verbose' 182 is true). 183 """ 184 from distutils.util import grok_environment_error 185 global _path_created 186 187 if verbose >= 1: 188 log.info("removing '%s' (and everything under it)", directory) 189 if dry_run: 190 return 191 cmdtuples = [] 192 _build_cmdtuple(directory, cmdtuples) 193 for cmd in cmdtuples: 194 try: 195 cmd[0](cmd[1]) 196 # remove dir from cache if it's already there 197 abspath = os.path.abspath(cmd[1]) 198 if abspath in _path_created: 199 del _path_created[abspath] 200 except (IOError, OSError), exc: 201 log.warn(grok_environment_error( 202 exc, "error removing %s: " % directory)) 203 204def ensure_relative(path): 205 """Take the full path 'path', and make it a relative path. 206 207 This is useful to make 'path' the second argument to os.path.join(). 208 """ 209 drive, path = os.path.splitdrive(path) 210 if path[0:1] == os.sep: 211 path = drive + path[1:] 212 return path 213