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     # __init__ ()
  97
  98
  99     # XXX A more explicit way to customize dry_run would be better.
 100
 101     def __getattr__ (self, attr):
 102         if attr == 'dry_run':
 103             myval = getattr(self, "_" + attr)
 104             if myval is None:
 105                 return getattr(self.distribution, attr)
 106             else:
 107                 return myval
 108         else:
 109             raise AttributeError, attr
 110
 111
 112     def ensure_finalized (self):
 113         if not self.finalized:
 114             self.finalize_options()
 115         self.finalized = 1
 116
 117
 118     # Subclasses must define:
 119     #   initialize_options()
 120     #     provide default values for all options; may be customized by
 121     #     setup script, by options from config file(s), or by command-line
 122     #     options
 123     #   finalize_options()
 124     #     decide on the final values for all options; this is called
 125     #     after all possible intervention from the outside world
 126     #     (command-line, option file, etc.) has been processed
 127     #   run()
 128     #     run the command: do whatever it is we're here to do,
 129     #     controlled by the command's various option values
 130
 131     def initialize_options (self):
 132         """Set default values for all the options that this command
 133         supports.  Note that these defaults may be overridden by other
 134         commands, by the setup script, by config files, or by the
 135         command-line.  Thus, this is not the place to code dependencies
 136         between options; generally, 'initialize_options()' implementations
 137         are just a bunch of "self.foo = None" assignments.
 138
 139         This method must be implemented by all command classes.
 140         """
 141         raise RuntimeError, \
 142               "abstract method -- subclass %s must override" % self.__class__
 143
 144     def finalize_options (self):
 145         """Set final values for all the options that this command supports.
 146         This is always called as late as possible, ie.  after any option
 147         assignments from the command-line or from other commands have been
 148         done.  Thus, this is the place to code option dependencies: if
 149         'foo' depends on 'bar', then it is safe to set 'foo' from 'bar' as
 150         long as 'foo' still has the same value it was assigned in
 151         'initialize_options()'.
 152
 153         This method must be implemented by all command classes.
 154         """
 155         raise RuntimeError, \
 156               "abstract method -- subclass %s must override" % self.__class__
 157
 158
 159     def dump_options(self, header=None, indent=""):
 160         from distutils.fancy_getopt import longopt_xlate
 161         if header is None:
 162             header = "command options for '%s':" % self.get_command_name()
 163         self.announce(indent + header, level=log.INFO)
 164         indent = indent + "  "
 165         for (option, _, _) in self.user_options:
 166             option = option.translate(longopt_xlate)
 167             if option[-1] == "=":
 168                 option = option[:-1]
 169             value = getattr(self, option)
 170             self.announce(indent + "%s = %s" % (option, value),
 171                           level=log.INFO)
 172
 173     def run (self):
 174         """A command's raison d'etre: carry out the action it exists to
 175         perform, controlled by the options initialized in
 176         'initialize_options()', customized by other commands, the setup
 177         script, the command-line, and config files, and finalized in
 178         'finalize_options()'.  All terminal output and filesystem
 179         interaction should be done by 'run()'.
 180
 181         This method must be implemented by all command classes.
 182         """
 183
 184         raise RuntimeError, \
 185               "abstract method -- subclass %s must override" % self.__class__
 186
 187     def announce (self, msg, level=1):
 188         """If the current verbosity level is of greater than or equal to
 189         'level' print 'msg' to stdout.
 190         """
 191         log.log(level, msg)
 192
 193     def debug_print (self, msg):
 194         """Print 'msg' to stdout if the global DEBUG (taken from the
 195         DISTUTILS_DEBUG environment variable) flag is true.
 196         """
 197         from distutils.debug import DEBUG
 198         if DEBUG:
 199             print msg
 200             sys.stdout.flush()
 201
 202
 203
 204     # -- Option validation methods -------------------------------------
 205     # (these are very handy in writing the 'finalize_options()' method)
 206     #
 207     # NB. the general philosophy here is to ensure that a particular option
 208     # value meets certain type and value constraints.  If not, we try to
 209     # force it into conformance (eg. if we expect a list but have a string,
 210     # split the string on comma and/or whitespace).  If we can't force the
 211     # option into conformance, raise DistutilsOptionError.  Thus, command
 212     # classes need do nothing more than (eg.)
 213     #   self.ensure_string_list('foo')
 214     # and they can be guaranteed that thereafter, self.foo will be
 215     # a list of strings.
 216
 217     def _ensure_stringlike (self, option, what, default=None):
 218         val = getattr(self, option)
 219         if val is None:
 220             setattr(self, option, default)
 221             return default
 222         elif not isinstance(val, str):
 223             raise DistutilsOptionError, \
 224                   "'%s' must be a %s (got `%s`)" % (option, what, val)
 225         return val
 226
 227     def ensure_string (self, option, default=None):
 228         """Ensure that 'option' is a string; if not defined, set it to
 229         'default'.
 230         """
 231         self._ensure_stringlike(option, "string", default)
 232
 233     def ensure_string_list (self, option):
 234         """Ensure that 'option' is a list of strings.  If 'option' is
 235         currently a string, we split it either on /,\s*/ or /\s+/, so
 236         "foo bar baz", "foo,bar,baz", and "foo,   bar baz" all become
 237         ["foo", "bar", "baz"].
 238         """
 239         val = getattr(self, option)
 240         if val is None:
 241             return
 242         elif isinstance(val, str):
 243             setattr(self, option, re.split(r',\s*|\s+', val))
 244         else:
 245             if isinstance(val, list):
 246                 # checks if all elements are str
 247                 ok = 1
 248                 for element in val:
 249                     if not isinstance(element, str):
 250                         ok = 0
 251                         break
 252             else:
 253                 ok = 0
 254
 255             if not ok:
 256                 raise DistutilsOptionError, \
 257                     "'%s' must be a list of strings (got %r)" % \
 258                         (option, val)
 259
 260
 261     def _ensure_tested_string (self, option, tester,
 262                                what, error_fmt, default=None):
 263         val = self._ensure_stringlike(option, what, default)
 264         if val is not None and not tester(val):
 265             raise DistutilsOptionError, \
 266                   ("error in '%s' option: " + error_fmt) % (option, val)
 267
 268     def ensure_filename (self, option):
 269         """Ensure that 'option' is the name of an existing file."""
 270         self._ensure_tested_string(option, os.path.isfile,
 271                                    "filename",
 272                                    "'%s' does not exist or is not a file")
 273
 274     def ensure_dirname (self, option):
 275         self._ensure_tested_string(option, os.path.isdir,
 276                                    "directory name",
 277                                    "'%s' does not exist or is not a directory")
 278
 279
 280     # -- Convenience methods for commands ------------------------------
 281
 282     def get_command_name (self):
 283         if hasattr(self, 'command_name'):
 284             return self.command_name
 285         else:
 286             return self.__class__.__name__
 287
 288
 289     def set_undefined_options (self, src_cmd, *option_pairs):
 290         """Set the values of any "undefined" options from corresponding
 291         option values in some other command object.  "Undefined" here means
 292         "is None", which is the convention used to indicate that an option
 293         has not been changed between 'initialize_options()' and
 294         'finalize_options()'.  Usually called from 'finalize_options()' for
 295         options that depend on some other command rather than another
 296         option of the same command.  'src_cmd' is the other command from
 297         which option values will be taken (a command object will be created
 298         for it if necessary); the remaining arguments are
 299         '(src_option,dst_option)' tuples which mean "take the value of
 300         'src_option' in the 'src_cmd' command object, and copy it to
 301         'dst_option' in the current command object".
 302         """
 303
 304         # Option_pairs: list of (src_option, dst_option) tuples
 305
 306         src_cmd_obj = self.distribution.get_command_obj(src_cmd)
 307         src_cmd_obj.ensure_finalized()
 308         for (src_option, dst_option) in option_pairs:
 309             if getattr(self, dst_option) is None:
 310                 setattr(self, dst_option,
 311                         getattr(src_cmd_obj, src_option))
 312
 313
 314     def get_finalized_command (self, command, create=1):
 315         """Wrapper around Distribution's 'get_command_obj()' method: find
 316         (create if necessary and 'create' is true) the command object for
 317         'command', call its 'ensure_finalized()' method, and return the
 318         finalized command object.
 319         """
 320         cmd_obj = self.distribution.get_command_obj(command, create)
 321         cmd_obj.ensure_finalized()
 322         return cmd_obj
 323
 324     # XXX rename to 'get_reinitialized_command()'? (should do the
 325     # same in dist.py, if so)
 326     def reinitialize_command (self, command, reinit_subcommands=0):
 327         return self.distribution.reinitialize_command(
 328             command, reinit_subcommands)
 329
 330     def run_command (self, command):
 331         """Run some other command: uses the 'run_command()' method of
 332         Distribution, which creates and finalizes the command object if
 333         necessary and then invokes its 'run()' method.
 334         """
 335         self.distribution.run_command(command)
 336
 337
 338     def get_sub_commands (self):
 339         """Determine the sub-commands that are relevant in the current
 340         distribution (ie., that need to be run).  This is based on the
 341         'sub_commands' class attribute: each tuple in that list may include
 342         a method that we call to determine if the subcommand needs to be
 343         run for the current distribution.  Return a list of command names.
 344         """
 345         commands = []
 346         for (cmd_name, method) in self.sub_commands:
 347             if method is None or method(self):
 348                 commands.append(cmd_name)
 349         return commands
 350
 351
 352     # -- External world manipulation -----------------------------------
 353
 354     def warn (self, msg):
 355         sys.stderr.write("warning: %s: %s\n" %
 356                          (self.get_command_name(), msg))
 357
 358
 359     def execute (self, func, args, msg=None, level=1):
 360         util.execute(func, args, msg, dry_run=self.dry_run)
 361
 362
 363     def mkpath (self, name, mode=0777):
 364         dir_util.mkpath(name, mode, dry_run=self.dry_run)
 365
 366
 367     def copy_file (self, infile, outfile,
 368                    preserve_mode=1, preserve_times=1, link=None, level=1):
 369         """Copy a file respecting verbose, dry-run and force flags.  (The
 370         former two default to whatever is in the Distribution object, and
 371         the latter defaults to false for commands that don't define it.)"""
 372
 373         return file_util.copy_file(
 374             infile, outfile,
 375             preserve_mode, preserve_times,
 376             not self.force,
 377             link,
 378             dry_run=self.dry_run)
 379
 380
 381     def copy_tree (self, infile, outfile,
 382                    preserve_mode=1, preserve_times=1, preserve_symlinks=0,
 383                    level=1):
 384         """Copy an entire directory tree respecting verbose, dry-run,
 385         and force flags.
 386         """
 387         return dir_util.copy_tree(
 388             infile, outfile,
 389             preserve_mode,preserve_times,preserve_symlinks,
 390             not self.force,
 391             dry_run=self.dry_run)
 392
 393     def move_file (self, src, dst, level=1):
 394         """Move a file respectin dry-run flag."""
 395         return file_util.move_file(src, dst, dry_run = self.dry_run)
 396
 397     def spawn (self, cmd, search_path=1, level=1):
 398         """Spawn an external command respecting dry-run flag."""
 399         from distutils.spawn import spawn
 400         spawn(cmd, search_path, dry_run= self.dry_run)
 401
 402     def make_archive (self, base_name, format,
 403                       root_dir=None, base_dir=None):
 404         return archive_util.make_archive(
 405             base_name, format, root_dir, base_dir, dry_run=self.dry_run)
 406
 407
 408     def make_file(self, infiles, outfile, func, args,
 409                   exec_msg=None, skip_msg=None, level=1):
 410         """Special case of 'execute()' for operations that process one or
 411         more input files and generate one output file.  Works just like
 412         'execute()', except the operation is skipped and a different
 413         message printed if 'outfile' already exists and is newer than all
 414         files listed in 'infiles'.  If the command defined 'self.force',
 415         and it is true, then the command is unconditionally run -- does no
 416         timestamp checks.
 417         """
 418         if skip_msg is None:
 419             skip_msg = "skipping %s (inputs unchanged)" % outfile
 420
 421         # Allow 'infiles' to be a single string
 422         if isinstance(infiles, str):
 423             infiles = (infiles,)
 424         elif not isinstance(infiles, (list, tuple)):
 425             raise TypeError, \
 426                   "'infiles' must be a string, or a list or tuple of strings"
 427
 428         if exec_msg is None:
 429             exec_msg = "generating %s from %s" % \
 430                        (outfile, ', '.join(infiles))
 431
 432         # If 'outfile' must be regenerated (either because it doesn't
 433         # exist, is out-of-date, or the 'force' flag is true) then
 434         # perform the action that presumably regenerates it
 435         if self.force or dep_util.newer_group(infiles, outfile):
 436             self.execute(func, args, exec_msg, level)
 437
 438         # Otherwise, print the "skip" message
 439         else:
 440             log.debug(skip_msg)
 441
 442     # make_file ()
 443
 444 # class Command
 445
 446
 447 # XXX 'install_misc' class not currently used -- it was the base class for
 448 # both 'install_scripts' and 'install_data', but they outgrew it.  It might
 449 # still be useful for 'install_headers', though, so I'm keeping it around
 450 # for the time being.
 451
 452 class install_misc (Command):
 453     """Common base class for installing some files in a subdirectory.
 454     Currently used by install_data and install_scripts.
 455     """
 456
 457     user_options = [('install-dir=', 'd', "directory to install the files to")]
 458
 459     def initialize_options (self):
 460         self.install_dir = None
 461         self.outfiles = []
 462
 463     def _install_dir_from (self, dirname):
 464         self.set_undefined_options('install', (dirname, 'install_dir'))
 465
 466     def _copy_files (self, filelist):
 467         self.outfiles = []
 468         if not filelist:
 469             return
 470         self.mkpath(self.install_dir)
 471         for f in filelist:
 472             self.copy_file(f, self.install_dir)
 473             self.outfiles.append(os.path.join(self.install_dir, f))
 474
 475     def get_outputs (self):
 476         return self.outfiles