Lib/distutils/dir_util.py

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