Deleted some crufty comments and code.

A host of improvements in preparation for the 'bdist' command:
  - added 'get_outputs()' method (all the other improvements were to support
    this addition)
  - made 'find_package_modules()' and 'find_modules()' return similar
    values (list of (package, module, module_filename) tuples)
  - factored 'find_all_modules()' out of 'get_source_files()' (needed
    by 'get_outputs()')
  - factored 'get_module_outfile()' out of 'build_module()' (also needed
    by 'get_outputs()')
  - various little tweaks, improvements, comment/doc updates

Lib/distutils/command/build_py.py

@@ -58,17 +58,6 @@ class build_py (Command):
         # installation will look like (ie. we preserve mode when
         # installing).
 
-        # XXX copy_file does *not* preserve MacOS-specific file metadata.
-        # If this is a problem for building/installing Python modules, then
-        # we'll have to fix copy_file.  (And what about installing scripts,
-        # when the time comes for that -- does MacOS use its special
-        # metadata to know that a file is meant to be interpreted by
-        # Python?)
-
-        infiles = []
-        outfiles = []
-        missing = []
-
         # Two options control which modules will be installed: 'packages'
         # and 'modules'.  The former lets us work with whole packages, not
         # specifying individual modules at all; the latter is for
@@ -171,16 +160,17 @@ class build_py (Command):
 
 
     def find_package_modules (self, package, package_dir):
+        self.check_package (package, package_dir)
         module_files = glob (os.path.join (package_dir, "*.py"))
-        module_pairs = []
+        modules = []
         setup_script = os.path.abspath (sys.argv[0])
 
         for f in module_files:
             abs_f = os.path.abspath (f)
             if abs_f != setup_script:
                 module = os.path.splitext (os.path.basename (f))[0]
-                module_pairs.append ((module, f))
+                modules.append ((package, module, f))
-        return module_pairs
+        return modules
 
 
     def find_modules (self):
@@ -222,14 +212,19 @@ class build_py (Command):
             if not self.check_module (module, module_file):
                 continue
 
-            modules.append ((module, package, module_file))
+            modules.append ((package, module, module_file))
 
         return modules
 
     # find_modules ()
 
 
-    def get_source_files (self):
+    def find_all_modules (self):
+        """Compute the list of all modules that will be built, whether
+        they are specified one-module-at-a-time ('self.modules') or
+        by whole packages ('self.packages').  Return a list of tuples
+        (package, module, module_file), just like 'find_modules()' and
+        'find_package_modules()' do."""
 
         if self.modules:
             modules = self.find_modules ()
@@ -240,18 +235,37 @@ class build_py (Command):
                 m = self.find_package_modules (package, package_dir)
                 modules.extend (m)
 
-        # Both find_modules() and find_package_modules() return a list of
+        return modules
-        # tuples where the last element of each tuple is the filename --
+
-        # what a happy coincidence!
+    # find_all_modules ()
+
+
+    def get_source_files (self):
+
+        modules = self.find_all_modules ()
         filenames = []
         for module in modules:
             filenames.append (module[-1])
 
-        return filenames                
+        return filenames
+
+
+    def get_module_outfile (self, build_dir, package, module):
+        outfile_path = [build_dir] + list(package) + [module + ".py"]
+        return apply (os.path.join, outfile_path)
+
+
+    def get_outputs (self):
+        modules = self.find_all_modules ()
+        outputs = []
+        for (package, module, module_file) in modules:
+            package = string.split (package, '.')
+            outputs.append (self.get_module_outfile (self.build_lib,
+                                                     package, module))
+        return outputs
 
 
     def build_module (self, module, module_file, package):
-
         if type (package) is StringType:
             package = string.split (package, '.')
         elif type (package) not in (ListType, TupleType):
@@ -261,11 +275,7 @@ class build_py (Command):
         # Now put the module source file into the "build" area -- this is
         # easy, we just copy it somewhere under self.build_lib (the build
         # directory for Python source).
-        outfile_path = list (package)
+        outfile = self.get_module_outfile (self.build_lib, package, module)
-        outfile_path.append (module + ".py")
-        outfile_path.insert (0, self.build_lib)
-        outfile = apply (os.path.join, outfile_path)
-
         dir = os.path.dirname (outfile)
         self.mkpath (dir)
         self.copy_file (module_file, outfile, preserve_mode=0)
@@ -274,7 +284,7 @@ class build_py (Command):
     def build_modules (self):
 
         modules = self.find_modules()
-        for (module, package, module_file) in modules:
+        for (package, module, module_file) in modules:
 
             # Now "build" the module -- ie. copy the source file to
             # self.build_lib (the build directory for Python source).
@@ -288,20 +298,23 @@ class build_py (Command):
     def build_packages (self):
 
         for package in self.packages:
-            package_dir = self.get_package_dir (package)
-            self.check_package (package, package_dir)
 
-            # Get list of (module, module_file) tuples based on scanning
+            # Get list of (package, module, module_file) tuples based on
-            # the package directory.  Here, 'module' is the *unqualified*
+            # scanning the package directory.  'package' is only included
-            # module name (ie. no dots, no package -- we already know its
+            # in the tuple so that 'find_modules()' and
-            # package!), and module_file is the path to the .py file,
+            # 'find_package_tuples()' have a consistent interface; it's
-            # relative to the current directory (ie. including
+            # ignored here (apart from a sanity check).  Also, 'module' is
-            # 'package_dir').
+            # the *unqualified* module name (ie. no dots, no package -- we
+            # already know its package!), and 'module_file' is the path to
+            # the .py file, relative to the current directory
+            # (ie. including 'package_dir').
+            package_dir = self.get_package_dir (package)
             modules = self.find_package_modules (package, package_dir)
 
             # Now loop over the modules we found, "building" each one (just
             # copy it to self.build_lib).
-            for (module, module_file) in modules:
+            for (package_, module, module_file) in modules:
+                assert package == package_
                 self.build_module (module, module_file, package)
 
     # build_packages ()