• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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