23 # Regex to define acceptable Distutils command names.  This is not *quite*
26 # to look for a Python module named after the command.
47     to the Distutils commands specified on the command line.
58     # 'global_options' describes the command-line options that may be
62     # since every global option is also valid as a command option -- and we
144         filled in with real command objects by 'parse_command_line()'.
147         # Default values for our command-line options
156         # information here (and enough command-line options) that it's
164         # 'cmdclass' maps command names to class objects, so we
166         # we need to create a new command object, and 2) have a way
167         # for the setup script to override command classes
171         # are searched for.  The factory for command 'foo' is expected
174         # is raised if no named package provides the command being
180         # not necessarily a setup script run from the command-line.
184         # 'command_options' is where we store command options between
185         # parsing them (from config files, the command-line, etc.) and when
186         # they are actually needed -- ie. when the command in question is
191         # 'dist_files' is the list of (command, pyversion, file) that
220         # the caller at all.  'command_obj' maps command names to
221         # Command instances -- that's how we enforce that every command
225         # 'have_run' maps command names to boolean values; it keeps track
226         # of whether we have actually run a particular command, to make it
227         # cheap to "run" a command whenever we think we might need to -- if
230         # It's only safe to query 'have_run' for a command class that has
232         # command object is created, and replaced with a true value when
233         # the command is successfully run.  Thus it's probably best to use
242             # Pull out the set of command options and work on them
244             # command options will override any supplied redundantly
249                 for (command, cmd_options) in options.items():
250                     opt_dict = self.get_option_dict(command)
276         # no-user-cfg is handled before other command line args
294     def get_option_dict(self, command):  argument
295         """Get the option dictionary for a given command.  If that
296         command's option dictionary hasn't been created yet, then create it
300         dict = self.command_options.get(command)
302             dict = self.command_options[command] = {}
308         if commands is None:             # dump all command option dicts
323                               "no option dict for '%s' command" % cmd_name)
326                               "option dict for '%s' command:" % cmd_name)
437     # -- Command-line parsing methods ----------------------------------
440         """Parse the setup script's command line, taken from the
445         and options for that command.  Each new command terminates the
446         options for the previous command.  The allowed options for a
447         command are determined by the 'user_options' attribute of the
448         command class -- thus, we have to be able to load command classes
449         in order to parse the command line.  Any error in that 'options'
451         command-line raises DistutilsArgError.  If no Distutils commands
452         were found on the command line, raises DistutilsArgError.  Return
453         true if command-line was successfully parsed and we should carry
460         # that allows the user to interactively specify the "command line".
464         # We have to parse the command line a bit at a time -- global
465         # options, then the first command, then its options, and so on --
466         # because each command will be handled by a different class, and
468         # until we have loaded the command class, which doesn't happen
469         # until we know what the command is.
488         # "setup.py --help" and "setup.py --help command ...".  For the
492         # each command listed on the command line.
513             ("command-packages=", None,
518         """Parse the command-line options for a single command.
520         of arguments, starting with the current command (whose options
522         the next command at the front of the list; will be the empty
523         list if there are no more commands on the command line.  Returns
524         None if the user asked for help on this command.
527         from distutils.cmd import Command
529         # Pull the current command from the head of the command line
530         command = args[0]
531         if not command_re.match(command):
532             raise SystemExit("invalid command name '%s'" % command)
533         self.commands.append(command)
535         # Dig up the command class that implements this command, so we
536         # 1) know that it's a valid command, and 2) know which options
539             cmd_class = self.get_command_class(command)
543         # Require that the command class be derived from Command -- want
544         # to be sure that the basic "command" interface is implemented.
545         if not issubclass(cmd_class, Command):
547                 "command class %s must subclass Command" % cmd_class)
549         # Also make sure that the command object provides a list of its
553             msg = ("command class %s must provide "
557         # If the command class has a list of negative alias options,
564         # Check for help_options in command class.  They have a different
600         # Put the options from the command-line into their official
602         opt_dict = self.get_option_dict(command)
604             opt_dict[name] = ("command line", value)
610         instance, analogous to the .finalize_options() method of Command
623         """Show help for the setup script command-line in the form of
624         several lists of command-line options.  'parser' should be a
632         lists per-command help for every command name or command class
637         from distutils.cmd import Command
655         for command in self.commands:
656             if isinstance(command, type) and issubclass(command, Command):
657                 klass = command
659                 klass = self.get_command_class(command)
666             parser.print_help("Options for '%s' command:" % klass.__name__)
673         (--help-commands or the metadata display options) on the command
731         (listed in distutils.command.__all__) and "extra commands"
732         (mentioned in self.cmdclass, but not a standard command).  The
733         descriptions come from the command class attribute
736         import distutils.command
737         std_commands = distutils.command.__all__
762         """Get a list of (command, description) tuples.
764         distutils.command.__all__) and "extra commands" (mentioned in
765         self.cmdclass, but not a standard command).  The descriptions come
766         from the command class attribute 'description'.
770         import distutils.command
771         std_commands = distutils.command.__all__
793     # -- Command class/object methods ----------------------------------
802             if "distutils.command" not in pkgs:
803                 pkgs.insert(0, "distutils.command")
807     def get_command_class(self, command):  argument
808         """Return the class that implements the Distutils command named by
809         'command'.  First we check the 'cmdclass' dictionary; if the
810         command is mentioned there, we fetch the class object from the
811         dictionary and return it.  Otherwise we load the command module
812         ("distutils.command." + command) and fetch the command class from
819         klass = self.cmdclass.get(command)
824             module_name = "%s.%s" % (pkgname, command)
825             klass_name = command
837                     "invalid command '%s' (no class '%s' in module '%s')"
838                     % (command, klass_name, module_name))
840             self.cmdclass[command] = klass
843         raise DistutilsModuleError("invalid command '%s'" % command)
845     def get_command_obj(self, command, create=1):  argument
846         """Return the command object for 'command'.  Normally this object
847         is cached on a previous call to 'get_command_obj()'; if no command
848         object for 'command' is in the cache, then we either create and
851         cmd_obj = self.command_obj.get(command)
855                               "creating '%s' command object" % command)
857             klass = self.get_command_class(command)
858             cmd_obj = self.command_obj[command] = klass(self)
859             self.have_run[command] = 0
862             # or on the command line.  (NB. support for error
866             options = self.command_options.get(command)
875         attributes of an instance ('command').
877         'command_obj' must be a Command instance.  If 'option_dict' is not
878         supplied, uses the standard option dictionary for this command
886             self.announce("  setting options for '%s' command:" % command_name)
911                         "error in %s: command '%s' has no such option '%s'"
916     def reinitialize_command(self, command, reinit_subcommands=0):  argument
917         """Reinitializes a command to the state it was in when first
921         user-supplied values from the config files and command line.
922         You'll have to re-finalize the command object (by calling
926         'command' should be a command name (string) or command object.  If
927         'reinit_subcommands' is true, also reinitializes the command's
929         it has one).  See the "install" command for an example.  Only
933         Returns the reinitialized command object.
935         from distutils.cmd import Command
936         if not isinstance(command, Command):
937             command_name = command
938             command = self.get_command_obj(command_name)
940             command_name = command.get_command_name()
942         if not command.finalized:
943             return command
944         command.initialize_options()
945         command.finalized = 0
947         self._set_command_options(command)
950             for sub in command.get_sub_commands():
953         return command
961         """Run each command that was seen on the setup script command line.
962         Uses the list of commands found and cache of command objects
970     def run_command(self, command):  argument
971         """Do whatever it takes to run a command (including nothing at all,
972         if the command has already been run).  Specifically: if we have
973         already created and run the command named by 'command', return
974         silently without doing anything.  If the command named by 'command'
975         doesn't even have a command object yet, create one.  Then invoke
976         'run()' on that command object (or an existing one).
979         if self.have_run.get(command):
982         log.info("running %s", command)
983         cmd_obj = self.get_command_obj(command)
986         self.have_run[command] = 1
1250     """Convert a 4-tuple 'help_options' list as found in various command