"""Abstract base class for defining command classes, the "worker bees"

# 'sub_commands' formalizes the notion of a "family" of commands,

# eg. "install" as the parent with sub-commands "install_lib",

# "install_headers", etc. The parent of a family of commands

# defines 'sub_commands' as a class attribute; it's a list of

# (command_name : string, predicate : unbound_method | string | None)

# tuples, where 'predicate' is a method of the parent command that

# determines whether the corresponding command is applicable in the

# current situation. (Eg. we "install_headers" is only applicable if

# we have any C header files to install.) If 'predicate' is None,

# that command is always applicable.

#

# 'sub_commands' is usually defined at the *end* of a class, because

# predicates can be unbound methods, so they must already have been

# defined. The canonical example is the "install" command.

sub_commands = []

# -- Creation/initialization methods -------------------------------

def __init__(self, dist):

"""Create and initialize a new Command object. Most importantly,

# late import because of mutual dependence between these classes

from distutils.dist import Distribution

if not isinstance(dist, Distribution):

raise TypeError("dist must be a Distribution instance")

if self.__class__ is Command:

raise RuntimeError("Command is an abstract class")

self.distribution = dist

self.initialize_options()

# Per-command versions of the global flags, so that the user can

# customize Distutils' behaviour command-by-command and let some

# commands fall back on the Distribution's behaviour. None means

# "not defined, check self.distribution's copy", while 0 or 1 mean

# false and true (duh). Note that this means figuring out the real

# value of each flag is a touch complicated -- hence "self._dry_run"

# will be handled by __getattr__, below.

# XXX This needs to be fixed.

self._dry_run = None

# verbose is largely ignored, but needs to be set for

# backwards compatibility (I think)?

self.verbose = dist.verbose

# Some commands define a 'self.force' option to ignore file

# timestamps, but methods defined *here* assume that

# 'self.force' exists for all commands. So define it here

# just to be safe.

self.force = None

# The 'help' flag is just used for command-line parsing, so

# none of that complicated bureaucracy is needed.

self.help = 0

# 'finalized' records whether or not 'finalize_options()' has been

# called. 'finalize_options()' itself should not pay attention to

# this flag: it is the business of 'ensure_finalized()', which

# always calls 'finalize_options()', to respect/update it.

self.finalized = 0

# XXX A more explicit way to customize dry_run would be better.

def __getattr__(self, attr):

if attr == 'dry_run':

myval = getattr(self, "_" + attr)

if myval is None:

return getattr(self.distribution, attr)

else:

return myval

else:

raise AttributeError(attr)

def ensure_finalized(self):

if not self.finalized:

self.finalize_options()

self.finalized = 1

# Subclasses must define:

# initialize_options()

# provide default values for all options; may be customized by

# setup script, by options from config file(s), or by command-line

# options

# finalize_options()

# decide on the final values for all options; this is called

# after all possible intervention from the outside world

# (command-line, option file, etc.) has been processed

# run()

# run the command: do whatever it is we're here to do,

# controlled by the command's various option values

def initialize_options(self):

"""Set default values for all the options that this command

raise RuntimeError("abstract method -- subclass %s must override"

% self.__class__)

def finalize_options(self):

"""Set final values for all the options that this command supports.

raise RuntimeError("abstract method -- subclass %s must override"

% self.__class__)

def dump_options(self, header=None, indent=""):

from distutils.fancy_getopt import longopt_xlate

if header is None:

header = "command options for '%s':" % self.get_command_name()

self.announce(indent + header, level=log.INFO)

indent = indent + " "

for (option, _, _) in self.user_options:

option = option.translate(longopt_xlate)

if option[-1] == "=":

option = option[:-1]

value = getattr(self, option)

self.announce(indent + "%s = %s" % (option, value),

level=log.INFO)

def run(self):

"""A command's raison d'etre: carry out the action it exists to

raise RuntimeError("abstract method -- subclass %s must override"

% self.__class__)

def announce(self, msg, level=1):

"""If the current verbosity level is of greater than or equal to

log.log(level, msg)

def debug_print(self, msg):

"""Print 'msg' to stdout if the global DEBUG (taken from the

from distutils.debug import DEBUG

if DEBUG:

print(msg)

sys.stdout.flush()

# -- Option validation methods -------------------------------------

# (these are very handy in writing the 'finalize_options()' method)

#

# NB. the general philosophy here is to ensure that a particular option

# value meets certain type and value constraints. If not, we try to

# force it into conformance (eg. if we expect a list but have a string,

# split the string on comma and/or whitespace). If we can't force the

# option into conformance, raise DistutilsOptionError. Thus, command

# classes need do nothing more than (eg.)

# self.ensure_string_list('foo')

# and they can be guaranteed that thereafter, self.foo will be

# a list of strings.

def _ensure_stringlike(self, option, what, default=None):

val = getattr(self, option)

if val is None:

setattr(self, option, default)

return default

elif not isinstance(val, str):

raise DistutilsOptionError("'%s' must be a %s (got `%s`)"

% (option, what, val))

return val

def ensure_string(self, option, default=None):

"""Ensure that 'option' is a string; if not defined, set it to

self._ensure_stringlike(option, "string", default)

def ensure_string_list(self, option):

r"""Ensure that 'option' is a list of strings. If 'option' is

val = getattr(self, option)

if val is None:

return

elif isinstance(val, str):

setattr(self, option, re.split(r',\s*|\s+', val))

else:

if isinstance(val, list):

ok = all(isinstance(v, str) for v in val)

else:

ok = False

if not ok:

raise DistutilsOptionError(

"'%s' must be a list of strings (got %r)"

% (option, val))

def _ensure_tested_string(self, option, tester, what, error_fmt,

default=None):

val = self._ensure_stringlike(option, what, default)

if val is not None and not tester(val):

raise DistutilsOptionError(("error in '%s' option: " + error_fmt)

% (option, val))

def ensure_filename(self, option):

"""Ensure that 'option' is the name of an existing file."""

self._ensure_tested_string(option, os.path.isfile,

"filename",

"'%s' does not exist or is not a file")

def ensure_dirname(self, option):

self._ensure_tested_string(option, os.path.isdir,

"directory name",

"'%s' does not exist or is not a directory")

# -- Convenience methods for commands ------------------------------

def get_command_name(self):

if hasattr(self, 'command_name'):

return self.command_name

else:

return self.__class__.__name__

def set_undefined_options(self, src_cmd, *option_pairs):

"""Set the values of any "undefined" options from corresponding

# Option_pairs: list of (src_option, dst_option) tuples

src_cmd_obj = self.distribution.get_command_obj(src_cmd)

src_cmd_obj.ensure_finalized()

for (src_option, dst_option) in option_pairs:

if getattr(self, dst_option) is None:

setattr(self, dst_option, getattr(src_cmd_obj, src_option))

def get_finalized_command(self, command, create=1):

"""Wrapper around Distribution's 'get_command_obj()' method: find

cmd_obj = self.distribution.get_command_obj(command, create)

cmd_obj.ensure_finalized()

return cmd_obj

# XXX rename to 'get_reinitialized_command()'? (should do the

# same in dist.py, if so)

def reinitialize_command(self, command, reinit_subcommands=0):

return self.distribution.reinitialize_command(command,

reinit_subcommands)

def run_command(self, command):

"""Run some other command: uses the 'run_command()' method of

self.distribution.run_command(command)

def get_sub_commands(self):

"""Determine the sub-commands that are relevant in the current

commands = []

for (cmd_name, method) in self.sub_commands:

if method is None or method(self):

commands.append(cmd_name)

return commands

# -- External world manipulation -----------------------------------

def warn(self, msg):

log.warn("warning: %s: %s\n", self.get_command_name(), msg)

def execute(self, func, args, msg=None, level=1):

util.execute(func, args, msg, dry_run=self.dry_run)

def mkpath(self, name, mode=0o777):

dir_util.mkpath(name, mode, dry_run=self.dry_run)

def copy_file(self, infile, outfile, preserve_mode=1, preserve_times=1,

link=None, level=1):

"""Copy a file respecting verbose, dry-run and force flags. (The

return file_util.copy_file(infile, outfile, preserve_mode,

preserve_times, not self.force, link,

dry_run=self.dry_run)

def copy_tree(self, infile, outfile, preserve_mode=1, preserve_times=1,

preserve_symlinks=0, level=1):

"""Copy an entire directory tree respecting verbose, dry-run,

return dir_util.copy_tree(infile, outfile, preserve_mode,

preserve_times, preserve_symlinks,

not self.force, dry_run=self.dry_run)

def move_file (self, src, dst, level=1):

"""Move a file respecting dry-run flag."""

return file_util.move_file(src, dst, dry_run=self.dry_run)

def spawn(self, cmd, search_path=1, level=1):

"""Spawn an external command respecting dry-run flag."""

from distutils.spawn import spawn

spawn(cmd, search_path, dry_run=self.dry_run)

def make_archive(self, base_name, format, root_dir=None, base_dir=None,

owner=None, group=None):

return archive_util.make_archive(base_name, format, root_dir, base_dir,

dry_run=self.dry_run,

owner=owner, group=group)

def make_file(self, infiles, outfile, func, args,

exec_msg=None, skip_msg=None, level=1):

"""Special case of 'execute()' for operations that process one or

if skip_msg is None:

skip_msg = "skipping %s (inputs unchanged)" % outfile

# Allow 'infiles' to be a single string

if isinstance(infiles, str):

infiles = (infiles,)

elif not isinstance(infiles, (list, tuple)):

raise TypeError(

"'infiles' must be a string, or a list or tuple of strings")

if exec_msg is None:

exec_msg = "generating %s from %s" % (outfile, ', '.join(infiles))

# If 'outfile' must be regenerated (either because it doesn't

# exist, is out-of-date, or the 'force' flag is true) then

# perform the action that presumably regenerates it

if self.force or dep_util.newer_group(infiles, outfile):

self.execute(func, args, exec_msg, level)

# Otherwise, print the "skip" message

else: