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