sys/lib/python/distutils/cmd.py

   1 """distutils.cmd
   2
   3 Provides the Command class, the base class for the command classes
   4 in the distutils.command package.
   5 """
   6
   7 # This module should be kept compatible with Python 2.1.
   8
   9 __revision__ = "$Id: cmd.py 37828 2004-11-10 22:23:15Z loewis $"
  10
  11 import sys, os, string, re
  12 from types import *
  13 from distutils.errors import *
  14 from distutils import util, dir_util, file_util, archive_util, dep_util
  15 from distutils import log
  16
  17 class Command:
  18     """Abstract base class for defining command classes, the "worker bees"
  19     of the Distutils.  A useful analogy for command classes is to think of
  20     them as subroutines with local variables called "options".  The options
  21     are "declared" in 'initialize_options()' and "defined" (given their
  22     final values, aka "finalized") in 'finalize_options()', both of which
  23     must be defined by every command class.  The distinction between the
  24     two is necessary because option values might come from the outside
  25     world (command line, config file, ...), and any options dependent on
  26     other options must be computed *after* these outside influences have
  27     been processed -- hence 'finalize_options()'.  The "body" of the
  28     subroutine, where it does all its work based on the values of its
  29     options, is the 'run()' method, which must also be implemented by every
  30     command class.
  31     """
  32
  33     # 'sub_commands' formalizes the notion of a "family" of commands,
  34     # eg. "install" as the parent with sub-commands "install_lib",
  35     # "install_headers", etc.  The parent of a family of commands
  36     # defines 'sub_commands' as a class attribute; it's a list of
  37     #    (command_name : string, predicate : unbound_method | string | None)
  38     # tuples, where 'predicate' is a method of the parent command that
  39     # determines whether the corresponding command is applicable in the
  40     # current situation.  (Eg. we "install_headers" is only applicable if
  41     # we have any C header files to install.)  If 'predicate' is None,
  42     # that command is always applicable.
  43     #
  44     # 'sub_commands' is usually defined at the *end* of a class, because
  45     # predicates can be unbound methods, so they must already have been
  46     # defined.  The canonical example is the "install" command.
  47     sub_commands = []
  48
  49
  50     # -- Creation/initialization methods -------------------------------
  51
  52     def __init__ (self, dist):
  53         """Create and initialize a new Command object.  Most importantly,
  54         invokes the 'initialize_options()' method, which is the real
  55         initializer and depends on the actual command being
  56         instantiated.
  57         """
  58         # late import because of mutual dependence between these classes
  59         from distutils.dist import Distribution
  60
  61         if not isinstance(dist, Distribution):
  62             raise TypeError, "dist must be a Distribution instance"
  63         if self.__class__ is Command:
  64             raise RuntimeError, "Command is an abstract class"
  65
  66         self.distribution = dist
  67         self.initialize_options()
  68
  69         # Per-command versions of the global flags, so that the user can
  70         # customize Distutils' behaviour command-by-command and let some
  71         # commands fall back on the Distribution's behaviour.  None means
  72         # "not defined, check self.distribution's copy", while 0 or 1 mean
  73         # false and true (duh).  Note that this means figuring out the real
  74         # value of each flag is a touch complicated -- hence "self._dry_run"
  75         # will be handled by __getattr__, below.
  76         # XXX This needs to be fixed.
  77         self._dry_run = None
  78
  79         # verbose is largely ignored, but needs to be set for
  80         # backwards compatibility (I think)?
  81         self.verbose = dist.verbose
  82
  83         # Some commands define a 'self.force' option to ignore file
  84         # timestamps, but methods defined *here* assume that
  85         # 'self.force' exists for all commands.  So define it here
  86         # just to be safe.
  87         self.force = None
  88
  89         # The 'help' flag is just used for command-line parsing, so
  90         # none of that complicated bureaucracy is needed.
  91         self.help = 0
  92
  93         # 'finalized' records whether or not 'finalize_options()' has been
  94         # called.  'finalize_options()' itself should not pay attention to
  95         # this flag: it is the business of 'ensure_finalized()', which
  96         # always calls 'finalize_options()', to respect/update it.
  97         self.finalized = 0
  98
  99     # __init__ ()
 100
 101
 102     # XXX A more explicit way to customize dry_run would be better.
 103
 104     def __getattr__ (self, attr):
 105         if attr == 'dry_run':
 106             myval = getattr(self, "_" + attr)
 107             if myval is None:
 108                 return getattr(self.distribution, attr)
 109             else:
 110                 return myval
 111         else:
 112             raise AttributeError, attr
 113
 114
 115     def ensure_finalized (self):
 116         if not self.finalized:
 117             self.finalize_options()
 118         self.finalized = 1
 119
 120
 121     # Subclasses must define:
 122     #   initialize_options()
 123     #     provide default values for all options; may be customized by
 124     #     setup script, by options from config file(s), or by command-line
 125     #     options
 126     #   finalize_options()
 127     #     decide on the final values for all options; this is called
 128     #     after all possible intervention from the outside world
 129     #     (command-line, option file, etc.) has been processed
 130     #   run()
 131     #     run the command: do whatever it is we're here to do,
 132     #     controlled by the command's various option values
 133
 134     def initialize_options (self):
 135         """Set default values for all the options that this command
 136         supports.  Note that these defaults may be overridden by other
 137         commands, by the setup script, by config files, or by the
 138         command-line.  Thus, this is not the place to code dependencies
 139         between options; generally, 'initialize_options()' implementations
 140         are just a bunch of "self.foo = None" assignments.
 141
 142         This method must be implemented by all command classes.
 143         """
 144         raise RuntimeError, \
 145               "abstract method -- subclass %s must override" % self.__class__
 146
 147     def finalize_options (self):
 148         """Set final values for all the options that this command supports.
 149         This is always called as late as possible, ie.  after any option
 150         assignments from the command-line or from other commands have been
 151         done.  Thus, this is the place to code option dependencies: if
 152         'foo' depends on 'bar', then it is safe to set 'foo' from 'bar' as
 153         long as 'foo' still has the same value it was assigned in
 154         'initialize_options()'.
 155
 156         This method must be implemented by all command classes.
 157         """
 158         raise RuntimeError, \
 159               "abstract method -- subclass %s must override" % self.__class__
 160
 161
 162     def dump_options (self, header=None, indent=""):
 163         from distutils.fancy_getopt import longopt_xlate
 164         if header is None:
 165             header = "command options for '%s':" % self.get_command_name()
 166         print indent + header
 167         indent = indent + "  "
 168         for (option, _, _) in self.user_options:
 169             option = string.translate(option, longopt_xlate)
 170             if option[-1] == "=":
 171                 option = option[:-1]
 172             value = getattr(self, option)
 173             print indent + "%s = %s" % (option, value)
 174
 175
 176     def run (self):
 177         """A command's raison d'etre: carry out the action it exists to
 178         perform, controlled by the options initialized in
 179         'initialize_options()', customized by other commands, the setup
 180         script, the command-line, and config files, and finalized in
 181         'finalize_options()'.  All terminal output and filesystem
 182         interaction should be done by 'run()'.
 183
 184         This method must be implemented by all command classes.
 185         """
 186
 187         raise RuntimeError, \
 188               "abstract method -- subclass %s must override" % self.__class__
 189
 190     def announce (self, msg, level=1):
 191         """If the current verbosity level is of greater than or equal to
 192         'level' print 'msg' to stdout.
 193         """
 194         log.log(level, msg)
 195
 196     def debug_print (self, msg):
 197         """Print 'msg' to stdout if the global DEBUG (taken from the
 198         DISTUTILS_DEBUG environment variable) flag is true.
 199         """
 200         from distutils.debug import DEBUG
 201         if DEBUG:
 202             print msg
 203             sys.stdout.flush()
 204
 205
 206
 207     # -- Option validation methods -------------------------------------
 208     # (these are very handy in writing the 'finalize_options()' method)
 209     #
 210     # NB. the general philosophy here is to ensure that a particular option
 211     # value meets certain type and value constraints.  If not, we try to
 212     # force it into conformance (eg. if we expect a list but have a string,
 213     # split the string on comma and/or whitespace).  If we can't force the
 214     # option into conformance, raise DistutilsOptionError.  Thus, command
 215     # classes need do nothing more than (eg.)
 216     #   self.ensure_string_list('foo')
 217     # and they can be guaranteed that thereafter, self.foo will be
 218     # a list of strings.
 219
 220     def _ensure_stringlike (self, option, what, default=None):
 221         val = getattr(self, option)
 222         if val is None:
 223             setattr(self, option, default)
 224             return default
 225         elif type(val) is not StringType:
 226             raise DistutilsOptionError, \
 227                   "'%s' must be a %s (got `%s`)" % (option, what, val)
 228         return val
 229
 230     def ensure_string (self, option, default=None):
 231         """Ensure that 'option' is a string; if not defined, set it to
 232         'default'.
 233         """
 234         self._ensure_stringlike(option, "string", default)
 235
 236     def ensure_string_list (self, option):
 237         """Ensure that 'option' is a list of strings.  If 'option' is
 238         currently a string, we split it either on /,\s*/ or /\s+/, so
 239         "foo bar baz", "foo,bar,baz", and "foo,   bar baz" all become
 240         ["foo", "bar", "baz"].
 241         """
 242         val = getattr(self, option)
 243         if val is None:
 244             return
 245         elif type(val) is StringType:
 246             setattr(self, option, re.split(r',\s*|\s+', val))
 247         else:
 248             if type(val) is ListType:
 249                 types = map(type, val)
 250                 ok = (types == [StringType] * len(val))
 251             else:
 252                 ok = 0
 253
 254             if not ok:
 255                 raise DistutilsOptionError, \
 256                       "'%s' must be a list of strings (got %r)" % \
 257                       (option, val)
 258
 259     def _ensure_tested_string (self, option, tester,
 260                                what, error_fmt, default=None):
 261         val = self._ensure_stringlike(option, what, default)
 262         if val is not None and not tester(val):
 263             raise DistutilsOptionError, \
 264                   ("error in '%s' option: " + error_fmt) % (option, val)
 265
 266     def ensure_filename (self, option):
 267         """Ensure that 'option' is the name of an existing file."""
 268         self._ensure_tested_string(option, os.path.isfile,
 269                                    "filename",
 270                                    "'%s' does not exist or is not a file")
 271
 272     def ensure_dirname (self, option):
 273         self._ensure_tested_string(option, os.path.isdir,
 274                                    "directory name",
 275                                    "'%s' does not exist or is not a directory")
 276
 277
 278     # -- Convenience methods for commands ------------------------------
 279
 280     def get_command_name (self):
 281         if hasattr(self, 'command_name'):
 282             return self.command_name
 283         else:
 284             return self.__class__.__name__
 285
 286
 287     def set_undefined_options (self, src_cmd, *option_pairs):
 288         """Set the values of any "undefined" options from corresponding
 289         option values in some other command object.  "Undefined" here means
 290         "is None", which is the convention used to indicate that an option
 291         has not been changed between 'initialize_options()' and
 292         'finalize_options()'.  Usually called from 'finalize_options()' for
 293         options that depend on some other command rather than another
 294         option of the same command.  'src_cmd' is the other command from
 295         which option values will be taken (a command object will be created
 296         for it if necessary); the remaining arguments are
 297         '(src_option,dst_option)' tuples which mean "take the value of
 298         'src_option' in the 'src_cmd' command object, and copy it to
 299         'dst_option' in the current command object".
 300         """
 301
 302         # Option_pairs: list of (src_option, dst_option) tuples
 303
 304         src_cmd_obj = self.distribution.get_command_obj(src_cmd)
 305         src_cmd_obj.ensure_finalized()
 306         for (src_option, dst_option) in option_pairs:
 307             if getattr(self, dst_option) is None:
 308                 setattr(self, dst_option,
 309                         getattr(src_cmd_obj, src_option))
 310
 311
 312     def get_finalized_command (self, command, create=1):
 313         """Wrapper around Distribution's 'get_command_obj()' method: find
 314         (create if necessary and 'create' is true) the command object for
 315         'command', call its 'ensure_finalized()' method, and return the
 316         finalized command object.
 317         """
 318         cmd_obj = self.distribution.get_command_obj(command, create)
 319         cmd_obj.ensure_finalized()
 320         return cmd_obj
 321
 322     # XXX rename to 'get_reinitialized_command()'? (should do the
 323     # same in dist.py, if so)
 324     def reinitialize_command (self, command, reinit_subcommands=0):
 325         return self.distribution.reinitialize_command(
 326             command, reinit_subcommands)
 327
 328     def run_command (self, command):
 329         """Run some other command: uses the 'run_command()' method of
 330         Distribution, which creates and finalizes the command object if
 331         necessary and then invokes its 'run()' method.
 332         """
 333         self.distribution.run_command(command)
 334
 335
 336     def get_sub_commands (self):
 337         """Determine the sub-commands that are relevant in the current
 338         distribution (ie., that need to be run).  This is based on the
 339         'sub_commands' class attribute: each tuple in that list may include
 340         a method that we call to determine if the subcommand needs to be
 341         run for the current distribution.  Return a list of command names.
 342         """
 343         commands = []
 344         for (cmd_name, method) in self.sub_commands:
 345             if method is None or method(self):
 346                 commands.append(cmd_name)
 347         return commands
 348
 349
 350     # -- External world manipulation -----------------------------------
 351
 352     def warn (self, msg):
 353         sys.stderr.write("warning: %s: %s\n" %
 354                          (self.get_command_name(), msg))
 355
 356
 357     def execute (self, func, args, msg=None, level=1):
 358         util.execute(func, args, msg, dry_run=self.dry_run)
 359
 360
 361     def mkpath (self, name, mode=0777):
 362         dir_util.mkpath(name, mode, dry_run=self.dry_run)
 363
 364
 365     def copy_file (self, infile, outfile,
 366                    preserve_mode=1, preserve_times=1, link=None, level=1):
 367         """Copy a file respecting verbose, dry-run and force flags.  (The
 368         former two default to whatever is in the Distribution object, and
 369         the latter defaults to false for commands that don't define it.)"""
 370
 371         return file_util.copy_file(
 372             infile, outfile,
 373             preserve_mode, preserve_times,
 374             not self.force,
 375             link,
 376             dry_run=self.dry_run)
 377
 378
 379     def copy_tree (self, infile, outfile,
 380                    preserve_mode=1, preserve_times=1, preserve_symlinks=0,
 381                    level=1):
 382         """Copy an entire directory tree respecting verbose, dry-run,
 383         and force flags.
 384         """
 385         return dir_util.copy_tree(
 386             infile, outfile,
 387             preserve_mode,preserve_times,preserve_symlinks,
 388             not self.force,
 389             dry_run=self.dry_run)
 390
 391     def move_file (self, src, dst, level=1):
 392         """Move a file respectin dry-run flag."""
 393         return file_util.move_file(src, dst, dry_run = self.dry_run)
 394
 395     def spawn (self, cmd, search_path=1, level=1):
 396         """Spawn an external command respecting dry-run flag."""
 397         from distutils.spawn import spawn
 398         spawn(cmd, search_path, dry_run= self.dry_run)
 399
 400     def make_archive (self, base_name, format,
 401                       root_dir=None, base_dir=None):
 402         return archive_util.make_archive(
 403             base_name, format, root_dir, base_dir, dry_run=self.dry_run)
 404
 405
 406     def make_file (self, infiles, outfile, func, args,
 407                    exec_msg=None, skip_msg=None, level=1):
 408         """Special case of 'execute()' for operations that process one or
 409         more input files and generate one output file.  Works just like
 410         'execute()', except the operation is skipped and a different
 411         message printed if 'outfile' already exists and is newer than all
 412         files listed in 'infiles'.  If the command defined 'self.force',
 413         and it is true, then the command is unconditionally run -- does no
 414         timestamp checks.
 415         """
 416         if exec_msg is None:
 417             exec_msg = "generating %s from %s" % \
 418                        (outfile, string.join(infiles, ', '))
 419         if skip_msg is None:
 420             skip_msg = "skipping %s (inputs unchanged)" % outfile
 421
 422
 423         # Allow 'infiles' to be a single string
 424         if type(infiles) is StringType:
 425             infiles = (infiles,)
 426         elif type(infiles) not in (ListType, TupleType):
 427             raise TypeError, \
 428                   "'infiles' must be a string, or a list or tuple of strings"
 429
 430         # If 'outfile' must be regenerated (either because it doesn't
 431         # exist, is out-of-date, or the 'force' flag is true) then
 432         # perform the action that presumably regenerates it
 433         if self.force or dep_util.newer_group (infiles, outfile):
 434             self.execute(func, args, exec_msg, level)
 435
 436         # Otherwise, print the "skip" message
 437         else:
 438             log.debug(skip_msg)
 439
 440     # make_file ()
 441
 442 # class Command
 443
 444
 445 # XXX 'install_misc' class not currently used -- it was the base class for
 446 # both 'install_scripts' and 'install_data', but they outgrew it.  It might
 447 # still be useful for 'install_headers', though, so I'm keeping it around
 448 # for the time being.
 449
 450 class install_misc (Command):
 451     """Common base class for installing some files in a subdirectory.
 452     Currently used by install_data and install_scripts.
 453     """
 454
 455     user_options = [('install-dir=', 'd', "directory to install the files to")]
 456
 457     def initialize_options (self):
 458         self.install_dir = None
 459         self.outfiles = []
 460
 461     def _install_dir_from (self, dirname):
 462         self.set_undefined_options('install', (dirname, 'install_dir'))
 463
 464     def _copy_files (self, filelist):
 465         self.outfiles = []
 466         if not filelist:
 467             return
 468         self.mkpath(self.install_dir)
 469         for f in filelist:
 470             self.copy_file(f, self.install_dir)
 471             self.outfiles.append(os.path.join(self.install_dir, f))
 472
 473     def get_outputs (self):
 474         return self.outfiles
 475
 476
 477 if __name__ == "__main__":
 478     print "ok"