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