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