Back to index

python3.2  3.2.2
Functions | Variables
distutils.dir_util Namespace Reference

Functions

def mkpath
def create_tree
def copy_tree
def _build_cmdtuple
def remove_tree
def ensure_relative

Variables

dictionary _path_created = {}

Detailed Description

distutils.dir_util

Utility functions for manipulating directories and directory trees.

Function Documentation

def distutils.dir_util._build_cmdtuple (   path,
  cmdtuples 
) [private]
Helper for remove_tree().

Definition at line 165 of file dir_util.py.

00165 
00166 def _build_cmdtuple(path, cmdtuples):
00167     """Helper for remove_tree()."""
00168     for f in os.listdir(path):
00169         real_f = os.path.join(path,f)
00170         if os.path.isdir(real_f) and not os.path.islink(real_f):
00171             _build_cmdtuple(real_f, cmdtuples)
00172         else:
00173             cmdtuples.append((os.remove, real_f))
00174     cmdtuples.append((os.rmdir, path))

Here is the caller graph for this function:

def distutils.dir_util.copy_tree (   src,
  dst,
  preserve_mode = 1,
  preserve_times = 1,
  preserve_symlinks = 0,
  update = 0,
  verbose = 1,
  dry_run = 0 
)
Copy an entire directory tree 'src' to a new location 'dst'.

Both 'src' and 'dst' must be directory names.  If 'src' is not a
directory, raise DistutilsFileError.  If 'dst' does not exist, it is
created with 'mkpath()'.  The end result of the copy is that every
file in 'src' is copied to 'dst', and directories under 'src' are
recursively copied to 'dst'.  Return the list of files that were
copied or might have been copied, using their output name.  The
return value is unaffected by 'update' or 'dry_run': it is simply
the list of all files under 'src', with the names changed to be
under 'dst'.

'preserve_mode' and 'preserve_times' are the same as for
'copy_file'; note that they only apply to regular files, not to
directories.  If 'preserve_symlinks' is true, symlinks will be
copied as symlinks (on platforms that support them!); otherwise
(the default), the destination of the symlink will be copied.
'update' and 'verbose' are the same as for 'copy_file'.

Definition at line 100 of file dir_util.py.

00100 
00101               preserve_symlinks=0, update=0, verbose=1, dry_run=0):
00102     """Copy an entire directory tree 'src' to a new location 'dst'.
00103 
00104     Both 'src' and 'dst' must be directory names.  If 'src' is not a
00105     directory, raise DistutilsFileError.  If 'dst' does not exist, it is
00106     created with 'mkpath()'.  The end result of the copy is that every
00107     file in 'src' is copied to 'dst', and directories under 'src' are
00108     recursively copied to 'dst'.  Return the list of files that were
00109     copied or might have been copied, using their output name.  The
00110     return value is unaffected by 'update' or 'dry_run': it is simply
00111     the list of all files under 'src', with the names changed to be
00112     under 'dst'.
00113 
00114     'preserve_mode' and 'preserve_times' are the same as for
00115     'copy_file'; note that they only apply to regular files, not to
00116     directories.  If 'preserve_symlinks' is true, symlinks will be
00117     copied as symlinks (on platforms that support them!); otherwise
00118     (the default), the destination of the symlink will be copied.
00119     'update' and 'verbose' are the same as for 'copy_file'.
00120     """
00121     from distutils.file_util import copy_file
00122 
00123     if not dry_run and not os.path.isdir(src):
00124         raise DistutilsFileError(
00125               "cannot copy tree '%s': not a directory" % src)
00126     try:
00127         names = os.listdir(src)
00128     except os.error as e:
00129         (errno, errstr) = e
00130         if dry_run:
00131             names = []
00132         else:
00133             raise DistutilsFileError(
00134                   "error listing files in '%s': %s" % (src, errstr))
00135 
00136     if not dry_run:
00137         mkpath(dst, verbose=verbose)
00138 
00139     outputs = []
00140 
00141     for n in names:
00142         src_name = os.path.join(src, n)
00143         dst_name = os.path.join(dst, n)
00144 
00145         if preserve_symlinks and os.path.islink(src_name):
00146             link_dest = os.readlink(src_name)
00147             if verbose >= 1:
00148                 log.info("linking %s -> %s", dst_name, link_dest)
00149             if not dry_run:
00150                 os.symlink(link_dest, dst_name)
00151             outputs.append(dst_name)
00152 
00153         elif os.path.isdir(src_name):
00154             outputs.extend(
00155                 copy_tree(src_name, dst_name, preserve_mode,
00156                           preserve_times, preserve_symlinks, update,
00157                           verbose=verbose, dry_run=dry_run))
00158         else:
00159             copy_file(src_name, dst_name, preserve_mode,
00160                       preserve_times, update, verbose=verbose,
00161                       dry_run=dry_run)
00162             outputs.append(dst_name)
00163 
00164     return outputs

Here is the call graph for this function:

Here is the caller graph for this function:

def distutils.dir_util.create_tree (   base_dir,
  files,
  mode = 0o777,
  verbose = 1,
  dry_run = 0 
)
Create all the empty directories under 'base_dir' needed to put 'files'
there.

'base_dir' is just the a name of a directory which doesn't necessarily
exist yet; 'files' is a list of filenames to be interpreted relative to
'base_dir'.  'base_dir' + the directory portion of every file in 'files'
will be created if it doesn't already exist.  'mode', 'verbose' and
'dry_run' flags are as for 'mkpath()'.

Definition at line 80 of file dir_util.py.

00080 
00081 def create_tree(base_dir, files, mode=0o777, verbose=1, dry_run=0):
00082     """Create all the empty directories under 'base_dir' needed to put 'files'
00083     there.
00084 
00085     'base_dir' is just the a name of a directory which doesn't necessarily
00086     exist yet; 'files' is a list of filenames to be interpreted relative to
00087     'base_dir'.  'base_dir' + the directory portion of every file in 'files'
00088     will be created if it doesn't already exist.  'mode', 'verbose' and
00089     'dry_run' flags are as for 'mkpath()'.
00090     """
00091     # First get the list of directories to create
00092     need_dir = set()
00093     for file in files:
00094         need_dir.add(os.path.join(base_dir, os.path.dirname(file)))
00095 
00096     # Now create them
00097     for dir in sorted(need_dir):
00098         mkpath(dir, mode, verbose=verbose, dry_run=dry_run)

Here is the call graph for this function:

Here is the caller graph for this function:

Take the full path 'path', and make it a relative path.

This is useful to make 'path' the second argument to os.path.join().

Definition at line 201 of file dir_util.py.

00201 
00202 def ensure_relative(path):
00203     """Take the full path 'path', and make it a relative path.
00204 
00205     This is useful to make 'path' the second argument to os.path.join().
00206     """
00207     drive, path = os.path.splitdrive(path)
00208     if path[0:1] == os.sep:
00209         path = drive + path[1:]
00210     return path

Here is the caller graph for this function:

def distutils.dir_util.mkpath (   name,
  mode = 0o777,
  verbose = 1,
  dry_run = 0 
)
Create a directory and any missing ancestor directories.

If the directory already exists (or if 'name' is the empty string, which
means the current directory, which of course exists), then do nothing.
Raise DistutilsFileError if unable to create some directory along the way
(eg. some sub-path exists, but is a file rather than a directory).
If 'verbose' is true, print a one-line summary of each mkdir to stdout.
Return the list of directories actually created.

Definition at line 17 of file dir_util.py.

00017 
00018 def mkpath(name, mode=0o777, verbose=1, dry_run=0):
00019     """Create a directory and any missing ancestor directories.
00020 
00021     If the directory already exists (or if 'name' is the empty string, which
00022     means the current directory, which of course exists), then do nothing.
00023     Raise DistutilsFileError if unable to create some directory along the way
00024     (eg. some sub-path exists, but is a file rather than a directory).
00025     If 'verbose' is true, print a one-line summary of each mkdir to stdout.
00026     Return the list of directories actually created.
00027     """
00028 
00029     global _path_created
00030 
00031     # Detect a common bug -- name is None
00032     if not isinstance(name, str):
00033         raise DistutilsInternalError(
00034               "mkpath: 'name' must be a string (got %r)" % (name,))
00035 
00036     # XXX what's the better way to handle verbosity? print as we create
00037     # each directory in the path (the current behaviour), or only announce
00038     # the creation of the whole path? (quite easy to do the latter since
00039     # we're not using a recursive algorithm)
00040 
00041     name = os.path.normpath(name)
00042     created_dirs = []
00043     if os.path.isdir(name) or name == '':
00044         return created_dirs
00045     if _path_created.get(os.path.abspath(name)):
00046         return created_dirs
00047 
00048     (head, tail) = os.path.split(name)
00049     tails = [tail]                      # stack of lone dirs to create
00050 
00051     while head and tail and not os.path.isdir(head):
00052         (head, tail) = os.path.split(head)
00053         tails.insert(0, tail)          # push next higher dir onto stack
00054 
00055     # now 'head' contains the deepest directory that already exists
00056     # (that is, the child of 'head' in 'name' is the highest directory
00057     # that does *not* exist)
00058     for d in tails:
00059         #print "head = %s, d = %s: " % (head, d),
00060         head = os.path.join(head, d)
00061         abs_head = os.path.abspath(head)
00062 
00063         if _path_created.get(abs_head):
00064             continue
00065 
00066         if verbose >= 1:
00067             log.info("creating %s", head)
00068 
00069         if not dry_run:
00070             try:
00071                 os.mkdir(head, mode)
00072             except OSError as exc:
00073                 if not (exc.errno == errno.EEXIST and os.path.isdir(head)):
00074                     raise DistutilsFileError(
00075                           "could not create '%s': %s" % (head, exc.args[-1]))
00076             created_dirs.append(head)
00077 
00078         _path_created[abs_head] = 1
00079     return created_dirs

Here is the caller graph for this function:

def distutils.dir_util.remove_tree (   directory,
  verbose = 1,
  dry_run = 0 
)
Recursively remove an entire directory tree.

Any errors are ignored (apart from being reported to stdout if 'verbose'
is true).

Definition at line 175 of file dir_util.py.

00175 
00176 def remove_tree(directory, verbose=1, dry_run=0):
00177     """Recursively remove an entire directory tree.
00178 
00179     Any errors are ignored (apart from being reported to stdout if 'verbose'
00180     is true).
00181     """
00182     from distutils.util import grok_environment_error
00183     global _path_created
00184 
00185     if verbose >= 1:
00186         log.info("removing '%s' (and everything under it)", directory)
00187     if dry_run:
00188         return
00189     cmdtuples = []
00190     _build_cmdtuple(directory, cmdtuples)
00191     for cmd in cmdtuples:
00192         try:
00193             cmd[0](cmd[1])
00194             # remove dir from cache if it's already there
00195             abspath = os.path.abspath(cmd[1])
00196             if abspath in _path_created:
00197                 del _path_created[abspath]
00198         except (IOError, OSError) as exc:
00199             log.warn(grok_environment_error(
00200                     exc, "error removing %s: " % directory))

Here is the call graph for this function:

Here is the caller graph for this function:


Variable Documentation

Definition at line 12 of file dir_util.py.