Lib/distutils/file_util.py

   1 """distutils.file_util
   2
   3 Utility functions for operating on single files.
   4 """
   5
   6 __revision__ = "$Id$"
   7
   8 import os
   9 from distutils.errors import DistutilsFileError
  10 from distutils import log
  11
  12 # for generating verbose output in 'copy_file()'
  13 _copy_action = {None: 'copying',
  14                 'hard': 'hard linking',
  15                 'sym': 'symbolically linking'}
  16
  17
  18 def _copy_file_contents(src, dst, buffer_size=16*1024):
  19     """Copy the file 'src' to 'dst'.
  20
  21     Both must be filenames. Any error opening either file, reading from
  22     'src', or writing to 'dst', raises DistutilsFileError.  Data is
  23     read/written in chunks of 'buffer_size' bytes (default 16k).  No attempt
  24     is made to handle anything apart from regular files.
  25     """
  26     # Stolen from shutil module in the standard library, but with
  27     # custom error-handling added.
  28     fsrc = None
  29     fdst = None
  30     try:
  31         try:
  32             fsrc = open(src, 'rb')
  33         except os.error, (errno, errstr):
  34             raise DistutilsFileError("could not open '%s': %s" % (src, errstr))
  35
  36         if os.path.exists(dst):
  37             try:
  38                 os.unlink(dst)
  39             except os.error, (errno, errstr):
  40                 raise DistutilsFileError(
  41                       "could not delete '%s': %s" % (dst, errstr))
  42
  43         try:
  44             fdst = open(dst, 'wb')
  45         except os.error, (errno, errstr):
  46             raise DistutilsFileError(
  47                   "could not create '%s': %s" % (dst, errstr))
  48
  49         while 1:
  50             try:
  51                 buf = fsrc.read(buffer_size)
  52             except os.error, (errno, errstr):
  53                 raise DistutilsFileError(
  54                       "could not read from '%s': %s" % (src, errstr))
  55
  56             if not buf:
  57                 break
  58
  59             try:
  60                 fdst.write(buf)
  61             except os.error, (errno, errstr):
  62                 raise DistutilsFileError(
  63                       "could not write to '%s': %s" % (dst, errstr))
  64
  65     finally:
  66         if fdst:
  67             fdst.close()
  68         if fsrc:
  69             fsrc.close()
  70
  71 def copy_file(src, dst, preserve_mode=1, preserve_times=1, update=0,
  72               link=None, verbose=1, dry_run=0):
  73     """Copy a file 'src' to 'dst'.
  74
  75     If 'dst' is a directory, then 'src' is copied there with the same name;
  76     otherwise, it must be a filename.  (If the file exists, it will be
  77     ruthlessly clobbered.)  If 'preserve_mode' is true (the default),
  78     the file's mode (type and permission bits, or whatever is analogous on
  79     the current platform) is copied.  If 'preserve_times' is true (the
  80     default), the last-modified and last-access times are copied as well.
  81     If 'update' is true, 'src' will only be copied if 'dst' does not exist,
  82     or if 'dst' does exist but is older than 'src'.
  83
  84     'link' allows you to make hard links (os.link) or symbolic links
  85     (os.symlink) instead of copying: set it to "hard" or "sym"; if it is
  86     None (the default), files are copied.  Don't set 'link' on systems that
  87     don't support it: 'copy_file()' doesn't check if hard or symbolic
  88     linking is available.
  89
  90     Under Mac OS, uses the native file copy function in macostools; on
  91     other systems, uses '_copy_file_contents()' to copy file contents.
  92
  93     Return a tuple (dest_name, copied): 'dest_name' is the actual name of
  94     the output file, and 'copied' is true if the file was copied (or would
  95     have been copied, if 'dry_run' true).
  96     """
  97     # XXX if the destination file already exists, we clobber it if
  98     # copying, but blow up if linking.  Hmmm.  And I don't know what
  99     # macostools.copyfile() does.  Should definitely be consistent, and
 100     # should probably blow up if destination exists and we would be
 101     # changing it (ie. it's not already a hard/soft link to src OR
 102     # (not update) and (src newer than dst).
 103
 104     from distutils.dep_util import newer
 105     from stat import ST_ATIME, ST_MTIME, ST_MODE, S_IMODE
 106
 107     if not os.path.isfile(src):
 108         raise DistutilsFileError(
 109               "can't copy '%s': doesn't exist or not a regular file" % src)
 110
 111     if os.path.isdir(dst):
 112         dir = dst
 113         dst = os.path.join(dst, os.path.basename(src))
 114     else:
 115         dir = os.path.dirname(dst)
 116
 117     if update and not newer(src, dst):
 118         if verbose >= 1:
 119             log.debug("not copying %s (output up-to-date)", src)
 120         return dst, 0
 121
 122     try:
 123         action = _copy_action[link]
 124     except KeyError:
 125         raise ValueError("invalid value '%s' for 'link' argument" % link)
 126
 127     if verbose >= 1:
 128         if os.path.basename(dst) == os.path.basename(src):
 129             log.info("%s %s -> %s", action, src, dir)
 130         else:
 131             log.info("%s %s -> %s", action, src, dst)
 132
 133     if dry_run:
 134         return (dst, 1)
 135
 136     # On Mac OS, use the native file copy routine
 137     if os.name == 'mac':
 138         import macostools
 139         try:
 140             macostools.copy(src, dst, 0, preserve_times)
 141         except os.error, exc:
 142             raise DistutilsFileError(
 143                   "could not copy '%s' to '%s': %s" % (src, dst, exc[-1]))
 144
 145     # If linking (hard or symbolic), use the appropriate system call
 146     # (Unix only, of course, but that's the caller's responsibility)
 147     elif link == 'hard':
 148         if not (os.path.exists(dst) and os.path.samefile(src, dst)):
 149             os.link(src, dst)
 150     elif link == 'sym':
 151         if not (os.path.exists(dst) and os.path.samefile(src, dst)):
 152             os.symlink(src, dst)
 153
 154     # Otherwise (non-Mac, not linking), copy the file contents and
 155     # (optionally) copy the times and mode.
 156     else:
 157         _copy_file_contents(src, dst)
 158         if preserve_mode or preserve_times:
 159             st = os.stat(src)
 160
 161             # According to David Ascher <da@ski.org>, utime() should be done
 162             # before chmod() (at least under NT).
 163             if preserve_times:
 164                 os.utime(dst, (st[ST_ATIME], st[ST_MTIME]))
 165             if preserve_mode:
 166                 os.chmod(dst, S_IMODE(st[ST_MODE]))
 167
 168     return (dst, 1)
 169
 170 # XXX I suspect this is Unix-specific -- need porting help!
 171 def move_file (src, dst, verbose=1, dry_run=0):
 172     """Move a file 'src' to 'dst'.
 173
 174     If 'dst' is a directory, the file will be moved into it with the same
 175     name; otherwise, 'src' is just renamed to 'dst'.  Return the new
 176     full name of the file.
 177
 178     Handles cross-device moves on Unix using 'copy_file()'.  What about
 179     other systems???
 180     """
 181     from os.path import exists, isfile, isdir, basename, dirname
 182     import errno
 183
 184     if verbose >= 1:
 185         log.info("moving %s -> %s", src, dst)
 186
 187     if dry_run:
 188         return dst
 189
 190     if not isfile(src):
 191         raise DistutilsFileError("can't move '%s': not a regular file" % src)
 192
 193     if isdir(dst):
 194         dst = os.path.join(dst, basename(src))
 195     elif exists(dst):
 196         raise DistutilsFileError(
 197               "can't move '%s': destination '%s' already exists" %
 198               (src, dst))
 199
 200     if not isdir(dirname(dst)):
 201         raise DistutilsFileError(
 202               "can't move '%s': destination '%s' not a valid path" % \
 203               (src, dst))
 204
 205     copy_it = 0
 206     try:
 207         os.rename(src, dst)
 208     except os.error, (num, msg):
 209         if num == errno.EXDEV:
 210             copy_it = 1
 211         else:
 212             raise DistutilsFileError(
 213                   "couldn't move '%s' to '%s': %s" % (src, dst, msg))
 214
 215     if copy_it:
 216         copy_file(src, dst, verbose=verbose)
 217         try:
 218             os.unlink(src)
 219         except os.error, (num, msg):
 220             try:
 221                 os.unlink(dst)
 222             except os.error:
 223                 pass
 224             raise DistutilsFileError(
 225                   ("couldn't move '%s' to '%s' by copy/delete: " +
 226                    "delete '%s' failed: %s") %
 227                   (src, dst, src, msg))
 228     return dst
 229
 230
 231 def write_file (filename, contents):
 232     """Create a file with the specified name and write 'contents' (a
 233     sequence of strings without line terminators) to it.
 234     """
 235     f = open(filename, "w")
 236     for line in contents:
 237         f.write(line + "\n")
 238     f.close()