Added the "sub-command" machinery to formalize the notion of "command

families" -- eg. install and its brood, build and its brood, and so forth.
Specifically: added the 'sub_commands' class attribute (empty list, sub-
classes must override it) and a comment describing it, and the
'get_sub_commands()' method.

1 files changed, 31 insertions, 0 deletions

diff --git a/Lib/distutils/cmd.py b/Lib/distutils/cmd.py
index 474f8f3..61d234b 100644
--- a/Lib/distutils/cmd.py
+++ b/Lib/distutils/cmd.py
@@ -31,6 +31,23 @@ class Command:
     command class.
     """
 
+    # '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):
@@ -310,6 +327,20 @@ class Command:
         self.distribution.run_command (command)
 
 
+    def get_sub_commands (self):
+        """Determine the sub-commands that are relevant in the current
+        distribution (ie., that need to be run).  This is based on the
+        'sub_commands' class attribute: each tuple in that list may include
+        a method that we call to determine if the subcommand needs to be
+        run for the current distribution.  Return a list of command names.
+        """
+        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):