Reformatted and updated many docstrings.

Lib/distutils/core.py

@@ -3,7 +3,8 @@
 The only module that needs to be imported to use the Distutils; provides
 the 'setup' function (which is to be called from the setup script).  Also
 indirectly provides the Distribution and Command classes, although they are
-really defined in distutils.dist and distutils.cmd."""
+really defined in distutils.dist and distutils.cmd.
+"""
 
 # created 1999/03/01, Greg Ward
 
@@ -37,36 +38,37 @@ DEBUG = os.environ.get('DISTUTILS_DEBUG')
 
 
 def setup (**attrs):
-    """The gateway to the Distutils: do everything your setup script
-       needs to do, in a highly flexible and user-driven way.  Briefly:
-       create a Distribution instance; parse the command-line, creating
-       and customizing instances of the command class for each command
-       found on the command-line; run each of those commands.
-
-       The Distribution instance might be an instance of a class
-       supplied via the 'distclass' keyword argument to 'setup'; if no
-       such class is supplied, then the 'Distribution' class (also in
-       this module) is instantiated.  All other arguments to 'setup'
-       (except for 'cmdclass') are used to set attributes of the
-       Distribution instance.
-
-       The 'cmdclass' argument, if supplied, is a dictionary mapping
-       command names to command classes.  Each command encountered on
-       the command line will be turned into a command class, which is in
-       turn instantiated; any class found in 'cmdclass' is used in place
-       of the default, which is (for command 'foo_bar') class 'foo_bar'
-       in module 'distutils.command.foo_bar'.  The command class must
-       provide a 'user_options' attribute which is a list of option
-       specifiers for 'distutils.fancy_getopt'.  Any command-line
-       options between the current and the next command are used to set
-       attributes of the current command object.
-
-       When the entire command-line has been successfully parsed, calls
-       the 'run()' method on each command object in turn.  This method
-       will be driven entirely by the Distribution object (which each
-       command object has a reference to, thanks to its constructor),
-       and the command-specific options that became attributes of each
-       command object."""
+    """The gateway to the Distutils: do everything your setup script needs
+    to do, in a highly flexible and user-driven way.  Briefly: create a
+    Distribution instance; find and parse config files; parse the command
+    line; run each of those commands using the options supplied to
+    'setup()' (as keyword arguments), in config files, and on the command
+    line.
+
+    The Distribution instance might be an instance of a class supplied via
+    the 'distclass' keyword argument to 'setup'; if no such class is
+    supplied, then the Distribution class (in dist.py) is instantiated.
+    All other arguments to 'setup' (except for 'cmdclass') are used to set
+    attributes of the Distribution instance.
+
+    The 'cmdclass' argument, if supplied, is a dictionary mapping command
+    names to command classes.  Each command encountered on the command line
+    will be turned into a command class, which is in turn instantiated; any
+    class found in 'cmdclass' is used in place of the default, which is
+    (for command 'foo_bar') class 'foo_bar' in module
+    'distutils.command.foo_bar'.  The command class must provide a
+    'user_options' attribute which is a list of option specifiers for
+    'distutils.fancy_getopt'.  Any command-line options between the current
+    and the next command are used to set attributes of the current command
+    object.
+
+    When the entire command-line has been successfully parsed, calls the
+    'run()' method on each command object in turn.  This method will be
+    driven entirely by the Distribution object (which each command object
+    has a reference to, thanks to its constructor), and the
+    command-specific options that became attributes of each command
+    object.
+    """
 
     from pprint import pprint               # for debugging output
 

Lib/distutils/dist.py

 """distutils.dist
 
 Provides the Distribution class, which represents the module distribution
-being built/installed/distributed."""
+being built/installed/distributed.
+"""
 
 # created 2000/04/03, Greg Ward
 # (extricated from core.py; actually dates back to the beginning)
@@ -25,20 +26,18 @@ command_re = re.compile (r'^[a-zA-Z]([a-zA-Z0-9_]*)$')
 
 
 class Distribution:
-    """The core of the Distutils.  Most of the work hiding behind
-       'setup' is really done within a Distribution instance, which
-       farms the work out to the Distutils commands specified on the
-       command line.
-
-       Clients will almost never instantiate Distribution directly,
-       unless the 'setup' function is totally inadequate to their needs.
-       However, it is conceivable that a client might wish to subclass
-       Distribution for some specialized purpose, and then pass the
-       subclass to 'setup' as the 'distclass' keyword argument.  If so,
-       it is necessary to respect the expectations that 'setup' has of
-       Distribution: it must have a constructor and methods
-       'parse_command_line()' and 'run_commands()' with signatures like
-       those described below."""
+    """The core of the Distutils.  Most of the work hiding behind 'setup'
+    is really done within a Distribution instance, which farms the work out
+    to the Distutils commands specified on the command line.
+
+    Setup scripts will almost never instantiate Distribution directly,
+    unless the 'setup()' function is totally inadequate to their needs.
+    However, it is conceivable that a setup script might wish to subclass
+    Distribution for some specialized purpose, and then pass the subclass
+    to 'setup()' as the 'distclass' keyword argument.  If so, it is
+    necessary to respect the expectations that 'setup' has of Distribution.
+    See the code for 'setup()', in core.py, for details.
+    """
 
 
     # 'global_options' describes the command-line options that may be
@@ -98,14 +97,14 @@ class Distribution:
     
     def __init__ (self, attrs=None):
         """Construct a new Distribution instance: initialize all the
-           attributes of a Distribution, and then uses 'attrs' (a
-           dictionary mapping attribute names to values) to assign
-           some of those attributes their "real" values.  (Any attributes
-           not mentioned in 'attrs' will be assigned to some null
-           value: 0, None, an empty list or dictionary, etc.)  Most
-           importantly, initialize the 'command_obj' attribute
-           to the empty dictionary; this will be filled in with real
-           command objects by 'parse_command_line()'."""
+        attributes of a Distribution, and then use 'attrs' (a dictionary
+        mapping attribute names to values) to assign some of those
+        attributes their "real" values.  (Any attributes not mentioned in
+        'attrs' will be assigned to some null value: 0, None, an empty list
+        or dictionary, etc.)  Most importantly, initialize the
+        'command_obj' attribute to the empty dictionary; this will be
+        filled in with real command objects by 'parse_command_line()'.
+        """
 
         # Default values for our command-line options
         self.verbose = 1
@@ -387,7 +386,6 @@ class Distribution:
     # parse_command_line()
 
     def _parse_command_opts (self, parser, args):
-
         """Parse the command-line options for a single command.
         'parser' must be a FancyGetopt instance; 'args' must be the list
         of arguments, starting with the current command (whose options
@@ -666,7 +664,6 @@ class Distribution:
         return cmd_obj
 
     def _set_command_options (self, command_obj, option_dict=None):
-
         """Set the options for 'command_obj' from 'option_dict'.  Basically
         this means copying elements of a dictionary ('option_dict') to
         attributes of an instance ('command').