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