1"""distutils.cmd 2 3Provides the Command class, the base class for the command classes 4in the distutils.command package. 5""" 6 7__revision__ = "$Id$" 8 9import sys, os, re 10from distutils.errors import DistutilsOptionError 11from distutils import util, dir_util, file_util, archive_util, dep_util 12from distutils import log 13 14class 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 respecting 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 433class 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 458