First checkin of real Distutils code.

Lib/distutils/errors.py

+"""distutils.errors
+
+Provides exceptions used by the Distutils modules.  Note that Distutils
+modules may raise standard exceptions; in particular, SystemExit is
+usually raised for errors that are obviously the end-user's fault
+(eg. bad command-line arguments).
+
+This module safe to use in "from ... import *" mode; it only exports
+symbols whose names start with "Distutils" and end with "Error"."""
+
+# created 1999/03/03, Greg Ward
+
+__rcsid__ = "$Id$"
+
+from types import *
+
+if type (RuntimeError) is ClassType:
+
+    # DistutilsError is the root of all Distutils evil.
+    class DistutilsError (Exception):
+        pass
+
+    # DistutilsModuleError is raised if we are unable to load an expected
+    # module, or find an expected class within some module
+    class DistutilsModuleError (DistutilsError):
+        pass
+
+    # DistutilsClassError is raised if we encounter a distribution or command
+    # class that's not holding up its end of the bargain.
+    class DistutilsClassError (DistutilsError):
+        pass
+
+    # DistutilsGetoptError (help me -- I have JavaProgrammersDisease!) is
+    # raised if the option table provided to fancy_getopt is bogus.
+    class DistutilsGetoptError (DistutilsError):
+        pass
+
+    # DistutilsArgError is raised by fancy_getopt in response to getopt.error;
+    # distutils.core then turns around and raises SystemExit from that.  (Thus
+    # client code should never see DistutilsArgError.)
+    class DistutilsArgError (DistutilsError):
+        pass
+
+    # DistutilsFileError is raised for any problems in the filesystem:
+    # expected file not found, etc.
+    class DistutilsFileError (DistutilsError):
+        pass
+
+    # DistutilsOptionError is raised anytime an attempt is made to access
+    # (get or set) an option that does not exist for a particular command
+    # (or for the distribution itself).
+    class DistutilsOptionError (DistutilsError):
+        pass
+
+# String-based exceptions
+else:
+    DistutilsError = 'DistutilsError'
+    DistutilsModuleError = 'DistutilsModuleError'
+    DistutilsClassError = 'DistutilsClassError'
+    DistutilsGetoptError = 'DistutilsGetoptError'
+    DistutilsArgError = 'DistutilsArgError'
+    DistutilsFileError = 'DistutilsFileError'
+    DistutilsOptionError = 'DistutilsOptionError'

Lib/distutils/fancy_getopt.py

+"""distutils.fancy_getopt
+
+Wrapper around the standard getopt module that provides the following
+additional features:
+  * short and long options are tied together
+  * options have help strings, so fancy_getopt could potentially
+    create a complete usage summary
+  * options set attributes of a passed-in object
+"""
+
+# created 1999/03/03, Greg Ward
+
+__rcsid__ = "$Id$"
+
+import string, re
+from types import *
+import getopt
+from distutils.errors import *
+
+# Much like command_re in distutils.core, this is close to but not quite
+# the same as a Python NAME -- except, in the spirit of most GNU
+# utilities, we use '-' in place of '_'.  (The spirit of LISP lives on!)
+# The similarities to NAME are again not a coincidence...
+longopt_re = re.compile (r'^[a-zA-Z]([a-zA-Z0-9-]*)$')
+
+# This is used to translate long options to legitimate Python identifiers
+# (for use as attributes of some object).
+longopt_xlate = string.maketrans ('-', '_')
+
+
+def fancy_getopt (options, object, args):
+
+    # The 'options' table is a list of 3-tuples:
+    #   (long_option, short_option, help_string)
+    # if an option takes an argument, its long_option should have '='
+    # appended; short_option should just be a single character, no ':' in
+    # any case.  If a long_option doesn't have a corresponding
+    # short_option, short_option should be None.  All option tuples must
+    # have long options.
+
+    # Build the short_opts string and long_opts list, remembering how
+    # the two are tied together
+
+    short_opts = []                     # we'll join 'em when done
+    long_opts = []
+    short2long = {}
+    attr_name = {}
+    takes_arg = {}
+
+    for (long, short, help) in options:
+        # Type-check the option names
+        if type (long) is not StringType or len (long) < 2:
+            raise DistutilsGetoptError, \
+                  "long option must be a string of length >= 2"
+
+        if (not ((short is None) or
+                 (type (short) is StringType and len (short) == 1))):
+            raise DistutilsGetoptError, \
+                  "short option must be None or string of length 1"
+
+        long_opts.append (long)
+
+        if long[-1] == '=':             # option takes an argument?
+            if short: short = short + ':'
+            long = long[0:-1]
+            takes_arg[long] = 1
+        else:
+            takes_arg[long] = 0
+
+        # Now enforce some bondage on the long option name, so we can later
+        # translate it to an attribute name in 'object'.  Have to do this a
+        # bit late to make sure we've removed any trailing '='.
+        if not longopt_re.match (long):
+            raise DistutilsGetoptError, \
+                  ("invalid long option name '%s' " +
+                   "(must be letters, numbers, hyphens only") % long
+
+        attr_name[long] = string.translate (long, longopt_xlate)
+        if short:
+            short_opts.append (short)
+            short2long[short[0]] = long
+
+    # end loop over 'options'
+
+    short_opts = string.join (short_opts)
+    try:
+        (opts, args) = getopt.getopt (args, short_opts, long_opts)
+    except getopt.error, msg:
+        raise DistutilsArgError, msg
+
+    for (opt, val) in opts:
+        if len (opt) == 2 and opt[0] == '-': # it's a short option
+            opt = short2long[opt[1]]
+
+        elif len (opt) > 2 and opt[0:2] == '--':
+            opt = opt[2:]
+
+        else:
+            raise RuntimeError, "getopt lies! (bad option string '%s')" % \
+                  opt
+
+        attr = attr_name[opt]
+        if takes_arg[opt]:
+            setattr (object, attr, val)
+        else:
+            if val == '':
+                setattr (object, attr, 1)
+            else:
+                raise RuntimeError, "getopt lies! (bad value '%s')" % value
+
+    # end loop over options found in 'args'
+
+    return args
+
+# end fancy_getopt()

Lib/distutils/options.py

+# XXX this is ridiculous! if commands need to pass options around,
+# they can just pass them via the 'run' method... what we REALLY need
+# is a way for commands to get at each other, via the Distribution!
+
+class Options:
+    """Used by Distribution and Command to encapsulate distribution
+       and command options -- parsing them from command-line arguments,
+       passing them between the distribution and command objects, etc."""
+
+    # -- Creation/initialization methods -------------------------------
+
+    def __init__ (self, owner):
+
+        # 'owner' is the object (presumably either a Distribution
+        # or Command instance) to which this set of options applies.
+        self.owner = owner
+
+        # The option table: maps option names to dictionaries, which
+        # look something like:
+        #    { 'longopt': long command-line option string (optional)
+        #      'shortopt': short option (1 char) (optional)
+        #      'type': 'string', 'boolean', or 'list'
+        #      'description': text description (eg. for help strings)
+        #      'default': default value for the option
+        #      'send': list of (cmd,option) tuples: send option down the line
+        #      'receive': (cmd,option) tuple: pull option from upstream
+        #    }
+        self.table = {}
+
+
+    def set_basic_options (self, *options):
+        """Add very basic options: no separate longopt, no fancy typing, no
+           send targets or receive destination.  The arguments should just
+           be {1..4}-tuples of
+              (name [, shortopt [, description [, default]]])
+           If name ends with '=', the option takes a string argument;
+           otherwise it's boolean."""
+
+        for opt in options:
+            if not (type (opt) is TupleType and 1 <= len (opt) <= 4):
+                raise ValueError, \
+                      ("invalid basic option record '%s': " + \
+                       "must be tuple of length 1 .. 4") % opt
+
+            elements = ('name', 'shortopt', 'description', 'default')
+            name = opt[0]
+            self.table[name] = {}
+            for i in range (1,4):
+                if len (opt) >= i:
+                    self.table[name][elements[i]] = opt[i]
+                else:
+                    break
+
+    # set_basic_options ()
+
+
+    def add_option (self, name, **args):
+
+        # XXX should probably sanity-check the keys of args
+        self.table[name] = args
+
+
+    # ------------------------------------------------------------------
+
+    # These are in the order that they will execute in to ensure proper
+    # prioritizing of option sources -- the default value is the most
+    # basic; it can be overridden by "client options" (the keyword args
+    # passed from setup.py to the 'setup' function); they in turn lose to
+    # options passed in "from above" (ie. from the Distribution, or from
+    # higher-level Commands); these in turn may be overridden by
+    # command-line arguments (which come from the end-user, the runner of
+    # setup.py).  Only when all this is done can we pass options down to
+    # other Commands.
+
+    # Hmmm, it also matters in which order Commands are processed: should a
+    # command-line option to 'make_blib' take precedence over the
+    # corresponding value passed down from its boss, 'build'?
+
+    def set_defaults (self):
+        pass
+
+    def set_client_options (self, options):
+        # 'self' should be a Distribution instance for this one --
+        # this is to process the kw args passed to 'setup'
+        pass
+
+    def receive_option (self, option, value):
+        # do we need to know the identity of the sender? don't
+        # think we should -- too much B&D
+
+        # oh, 'self' should be anything *but* a Distribution (ie.
+        # a Command instance) -- only Commands take orders from above!
+        # (ironically enough)
+        pass
+
+    def parse_command_line (self, args):
+        # here, 'self' can usefully be either a Distribution (for parsing
+        # "global" command-line options) or a Command (for "command-specific"
+        # options)
+        pass
+
+           
+    def send_option (self, option, dest):
+        # perhaps this should not take a dest, but send the option
+        # to all possible receivers?
+        pass
+
+
+    # ------------------------------------------------------------------
+
+# class Options

Lib/distutils/util.py

+"""distutils.util
+
+General-purpose utility functions used throughout the Distutils
+(especially in command classes).  Mostly filesystem manipulation, but
+not limited to that.  The functions in this module generally raise
+DistutilsFileError when they have problems with the filesystem, because
+os.error in pre-1.5.2 Python only gives the error message and not the
+file causing it."""
+
+# created 1999/03/08, Greg Ward
+
+__rcsid__ = "$Id$"
+
+import os
+from distutils.errors import *
+
+
+# I don't use os.makedirs because a) it's new to Python 1.5.2, and
+# b) it blows up if the directory already exists (I want to silently
+# succeed in that case).
+def mkpath (name, mode=0777, verbose=0):
+    """Create a directory and any missing ancestor directories.  If the
+       directory already exists, return silently.  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."""
+
+    # XXX what's the better way to handle verbosity? print as we create
+    # each directory in the path (the current behaviour), or only announce
+    # the creation of the whole path, and force verbose=0 on all sub-calls?
+
+    if os.path.isdir (name):
+        return
+
+    (head, tail) = os.path.split (name)
+    tails = [tail]                      # stack of lone dirs to create
+    
+    while head and tail and not os.path.isdir (head):
+        #print "splitting '%s': " % head,
+        (head, tail) = os.path.split (head)
+        #print "to ('%s','%s')" % (head, tail)
+        tails.insert (0, tail)          # push next higher dir onto stack
+
+    #print "stack of tails:", tails
+
+    # now 'head' contains the highest directory that already exists
+    for d in tails:
+        #print "head = %s, d = %s: " % (head, d),
+        head = os.path.join (head, d)
+        if verbose:
+            print "creating", head
+        try:
+            os.mkdir (head)
+        except os.error, (errno, errstr):
+            raise DistutilsFileError, "%s: %s" % (head, errstr)
+
+# mkpath ()
+
+
+def newer (file1, file2):
+    """Return true if file1 exists and is more recently modified than
+       file2, or if file1 exists and file2 doesn't.  Return false if both
+       exist and file2 is the same age or younger than file1.  Raises
+       DistutilsFileError if file1 does not exist."""
+
+    if not os.path.exists (file1):
+        raise DistutilsFileError, "file '%s' does not exist" % file1
+    if not os.path.exists (file2):
+        return 1
+
+    from stat import *
+    mtime1 = os.stat(file1)[ST_MTIME]
+    mtime2 = os.stat(file2)[ST_MTIME]
+
+    return mtime1 > mtime2
+
+# newer ()
+
+
+def make_file (src, dst, func, args,
+               verbose=0, update_message=None, noupdate_message=None):
+    """Makes 'dst' from 'src' (both filenames) by calling 'func' with
+       'args', but only if it needs to: i.e. if 'dst' does not exist or
+       'src' is newer than 'dst'."""
+
+    if newer (src, dst):
+        if verbose and update_message:
+            print update_message
+        apply (func, args)
+    else:
+        if verbose and noupdate_message:
+            print noupdate_message
+
+# make_file ()
+
+
+def _copy_file_contents (src, dst, buffer_size=16*1024):
+    """Copy the file 'src' to 'dst'; both must be filenames.  Any error
+       opening either file, reading from 'src', or writing to 'dst',
+       raises DistutilsFileError.  Data is read/written in chunks of
+       'buffer_size' bytes (default 16k).  No attempt is made to handle
+       anything apart from regular files."""
+
+    # Stolen from shutil module in the standard library, but with
+    # custom error-handling added.
+
+    fsrc = None
+    fdst = None
+    try:
+        try:
+            fsrc = open(src, 'rb')
+        except os.error, (errno, errstr):
+            raise DistutilsFileError, "could not open %s: %s" % (src, errstr)
+        
+        try:
+            fdst = open(dst, 'wb')
+        except os.error, (errno, errstr):
+            raise DistutilsFileError, "could not create %s: %s" % (dst, errstr)
+        
+        while 1:
+            try:
+                buf = fsrc.read (buffer_size)
+            except os.error, (errno, errstr):
+                raise DistutilsFileError, \
+                      "could not read from %s: %s" % (src, errstr)
+            
+            if not buf:
+                break
+
+            try:
+                fdst.write(buf)
+            except os.error, (errno, errstr):
+                raise DistutilsFileError, \
+                      "could not write to %s: %s" % (dst, errstr)
+            
+    finally:
+        if fdst:
+            fdst.close()
+        if fsrc:
+            fsrc.close()
+
+# _copy_file_contents()
+
+
+def copy_file (src, dst,
+               preserve_mode=1,
+               preserve_times=1,
+               update=0,
+               verbose=0):
+
+    """Copy a file 'src' to 'dst'.  If 'dst' is a directory, then 'src'
+       is copied there with the same name; otherwise, it must be a
+       filename.  (If the file exists, it will be ruthlessly clobbered.)
+       If 'preserve_mode' is true (the default), the file's mode (type
+       and permission bits, or whatever is analogous on the current
+       platform) is copied.  If 'preserve_times' is true (the default),
+       the last-modified and last-access times are copied as well.  If
+       'update' is true, 'src' will only be copied if 'dst' does not
+       exist, or if 'dst' does exist but is older than 'src'.  If
+       'verbose' is true, then a one-line summary of the copy will be
+       printed to stdout."""
+
+    # XXX doesn't copy Mac-specific metadata
+       
+    from shutil import copyfile
+    from stat import *
+
+    if not os.path.isfile (src):
+        raise DistutilsFileError, \
+              "can't copy %s:not a regular file" % src
+
+    if os.path.isdir (dst):
+        dir = dst
+        dst = os.path.join (dst, os.path.basename (src))
+    else:
+        dir = os.path.dirname (dst)
+
+    if update and not newer (src, dst):
+        return
+
+    if verbose:
+        print "copying %s -> %s" % (src, dir)
+
+    copyfile (src, dst)
+    if preserve_mode or preserve_times:
+        st = os.stat (src)
+        if preserve_mode:
+            os.chmod (dst, S_IMODE (st[ST_MODE]))
+        if preserve_times:
+            os.utime (dst, (st[ST_ATIME], st[ST_MTIME]))
+
+# copy_file ()
+
+
+def copy_tree (src, dst,
+               preserve_mode=1,
+               preserve_times=1,
+               preserve_symlinks=0,
+               update=0,
+               verbose=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 endresult of the copy is that
+       every file in 'src' is copied to 'dst', and directories under
+       'src' are recursively copied to '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'."""
+
+    if not os.path.isdir (src):
+        raise DistutilsFileError, \
+              "cannot copy tree %s: not a directory" % src    
+    try:
+        names = os.listdir (src)
+    except os.error, (errno, errstr):
+        raise DistutilsFileError, \
+              "error listing files in %s: %s" % (src, errstr)
+
+        
+    mkpath (dst, verbose=verbose)
+
+    for n in names:
+        src_name = os.path.join (src, n)
+        dst_name = os.path.join (dst, n)
+
+        if preserve_symlinks and os.path.islink (src_name):
+            link_dest = os.readlink (src_name)
+            os.symlink (link_dest, dst_name)
+        elif os.path.isdir (src_name):
+            copy_tree (src_name, dst_name,
+                       preserve_mode, preserve_times, preserve_symlinks,
+                       update, verbose)
+        else:
+            copy_file (src_name, dst_name,
+                       preserve_mode, preserve_times,
+                       update, verbose)
+
+# copy_tree ()