[Python-checkins] CVS: distutils/distutils dist.py,1.22,1.23 cmd.py,1.15,1.16 core.py,1.38,1.39
Greg Ward
python-dev@python.org
Thu, 1 Jun 2000 17:44:55 -0700
Update of /cvsroot/python/distutils/distutils
In directory slayer.i.sourceforge.net:/tmp/cvs-serv27024
Modified Files:
dist.py cmd.py core.py
Log Message:
Reformatted and updated many docstrings.
Index: dist.py
===================================================================
RCS file: /cvsroot/python/distutils/distutils/dist.py,v
retrieving revision 1.22
retrieving revision 1.23
diff -C2 -r1.22 -r1.23
*** dist.py 2000年06月01日 01:09:47 1.22
--- dist.py 2000年06月02日 00:44:53 1.23
***************
*** 2,11 ****
Provides the Distribution class, which represents the module distribution
! being built/installed/distributed."""
# created 2000年04月03日, Greg Ward
# (extricated from core.py; actually dates back to the beginning)
! __revision__ = "$Id: dist.py,v 1.22 2000年06月01日 01:09:47 gward Exp $"
import sys, os, string, re
--- 2,12 ----
Provides the Distribution class, which represents the module distribution
! being built/installed/distributed.
! """
# created 2000年04月03日, Greg Ward
# (extricated from core.py; actually dates back to the beginning)
! __revision__ = "$Id: dist.py,v 1.23 2000年06月02日 00:44:53 gward Exp $"
import sys, os, string, re
***************
*** 26,43 ****
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."""
--- 27,42 ----
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.
!
! 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.
! """
***************
*** 99,110 ****
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()'."""
# Default values for our command-line options
--- 98,109 ----
def __init__ (self, attrs=None):
"""Construct a new Distribution instance: initialize all the
! 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
***************
*** 388,392 ****
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
--- 387,390 ----
***************
*** 667,671 ****
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
--- 665,668 ----
Index: cmd.py
===================================================================
RCS file: /cvsroot/python/distutils/distutils/cmd.py,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -r1.15 -r1.16
*** cmd.py 2000年06月01日 01:08:52 1.15
--- cmd.py 2000年06月02日 00:44:53 1.16
***************
*** 2,11 ****
Provides the Command class, the base class for the command classes
! in the distutils.command package."""
# created 2000年04月03日, Greg Ward
# (extricated from core.py; actually dates back to the beginning)
! __revision__ = "$Id: cmd.py,v 1.15 2000年06月01日 01:08:52 gward Exp $"
import sys, os, string
--- 2,12 ----
Provides the Command class, the base class for the command classes
! in the distutils.command package.
! """
# created 2000年04月03日, Greg Ward
# (extricated from core.py; actually dates back to the beginning)
! __revision__ = "$Id: cmd.py,v 1.16 2000年06月02日 00:44:53 gward Exp $"
import sys, os, string
***************
*** 17,33 ****
class Command:
"""Abstract base class for defining command classes, the "worker bees"
! of the Distutils. A useful analogy for command classes is to
! think of them as subroutines with local variables called
! "options". The options are "declared" in 'initialize_options()'
! and "defined" (given their final values, aka "finalized") in
! 'finalize_options()', both of which must be defined by every
! command class. The distinction between the two is necessary
! because option values might come from the outside world (command
! line, option file, ...), and any options dependent on other
! options must be computed *after* these outside influences have
! been processed -- hence 'finalize_options()'. The "body" of the
! subroutine, where it does all its work based on the values of its
! options, is the 'run()' method, which must also be implemented by
! every command class."""
# -- Creation/initialization methods -------------------------------
--- 18,34 ----
class Command:
"""Abstract base class for defining command classes, the "worker bees"
! of the Distutils. A useful analogy for command classes is to think of
! them as subroutines with local variables called "options". The options
! are "declared" in 'initialize_options()' and "defined" (given their
! final values, aka "finalized") in 'finalize_options()', both of which
! must be defined by every command class. The distinction between the
! two is necessary because option values might come from the outside
! world (command line, config file, ...), and any options dependent on
! other options must be computed *after* these outside influences have
! been processed -- hence 'finalize_options()'. The "body" of the
! subroutine, where it does all its work based on the values of its
! options, is the 'run()' method, which must also be implemented by every
! command class.
! """
# -- Creation/initialization methods -------------------------------
***************
*** 35,42 ****
def __init__ (self, dist):
"""Create and initialize a new Command object. Most importantly,
! invokes the 'initialize_options()' method, which is the
! real initializer and depends on the actual command being
! instantiated."""
!
# late import because of mutual dependence between these classes
from distutils.dist import Distribution
--- 36,43 ----
def __init__ (self, dist):
"""Create and initialize a new Command object. Most importantly,
! invokes the 'initialize_options()' method, which is the real
! initializer and depends on the actual command being
! instantiated.
! """
# late import because of mutual dependence between these classes
from distutils.dist import Distribution
***************
*** 98,104 ****
# Subclasses must define:
# initialize_options()
! # provide default values for all options; may be overridden
! # by Distutils client, by command-line options, or by options
! # from option file
# finalize_options()
# decide on the final values for all options; this is called
--- 99,105 ----
# 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
***************
*** 111,136 ****
def initialize_options (self):
"""Set default values for all the options that this command
! supports. Note that these defaults may be overridden
! by the command-line supplied by the user; thus, this is
! not the place to code dependencies between options; generally,
! 'initialize_options()' implementations are just a bunch
! of "self.foo = None" assignments.
!
! This method must be implemented by all command classes."""
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. This is always called as late as possible, ie.
! after any option assignments from the command-line or from
! other commands have been done. Thus, this is the place to to
! code option dependencies: if 'foo' depends on 'bar', then it
! is safe to set 'foo' from 'bar' as long as 'foo' still has
! the same value it was assigned in 'initialize_options()'.
! This method must be implemented by all command classes."""
!
raise RuntimeError, \
"abstract method -- subclass %s must override" % self.__class__
--- 112,137 ----
def initialize_options (self):
"""Set default values for all the options that this command
! supports. Note that these defaults may be overridden by other
! commands, by the setup script, by config files, or by the
! command-line. Thus, this is not the place to code dependencies
! between options; generally, 'initialize_options()' implementations
! are just a bunch of "self.foo = None" assignments.
+ This method must be implemented by all command classes.
+ """
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.
! This is always called as late as possible, ie. after any option
! assignments from the command-line or from other commands have been
! done. Thus, this is the place to to code option dependencies: if
! 'foo' depends on 'bar', then it is safe to set 'foo' from 'bar' as
! long as 'foo' still has the same value it was assigned in
! 'initialize_options()'.
! This method must be implemented by all command classes.
! """
raise RuntimeError, \
"abstract method -- subclass %s must override" % self.__class__
***************
*** 152,163 ****
def run (self):
! """A command's raison d'etre: carry out the action it exists
! to perform, controlled by the options initialized in
! 'initialize_options()', customized by the user and other
! commands, and finalized in 'finalize_options()'. All
! terminal output and filesystem interaction should be done by
! 'run()'.
! This method must be implemented by all command classes."""
raise RuntimeError, \
--- 153,165 ----
def run (self):
! """A command's raison d'etre: carry out the action it exists to
! perform, controlled by the options initialized in
! 'initialize_options()', customized by other commands, the setup
! script, the command-line, and config files, and finalized in
! 'finalize_options()'. All terminal output and filesystem
! interaction should be done by 'run()'.
! This method must be implemented by all command classes.
! """
raise RuntimeError, \
***************
*** 165,172 ****
def announce (self, msg, level=1):
! """If the Distribution instance to which this command belongs
! has a verbosity level of greater than or equal to 'level'
! print 'msg' to stdout."""
!
if self.verbose >= level:
print msg
--- 167,173 ----
def announce (self, msg, level=1):
! """If the current verbosity level is of greater than or equal to
! 'level' print 'msg' to stdout.
! """
if self.verbose >= level:
print msg
***************
*** 184,199 ****
def set_undefined_options (self, src_cmd, *option_pairs):
"""Set the values of any "undefined" options from corresponding
! option values in some other command object. "Undefined" here
! means "is None", which is the convention used to indicate
! that an option has not been changed between
! 'set_initial_values()' and 'set_final_values()'. Usually
! called from 'set_final_values()' for options that depend on
! some other command rather than another option of the same
! command. 'src_cmd' is the other command from which option
! values will be taken (a command object will be created for it
! if necessary); the remaining arguments are
! '(src_option,dst_option)' tuples which mean "take the value
! of 'src_option' in the 'src_cmd' command object, and copy it
! to 'dst_option' in the current command object"."""
# Option_pairs: list of (src_option, dst_option) tuples
--- 185,200 ----
def set_undefined_options (self, src_cmd, *option_pairs):
"""Set the values of any "undefined" options from corresponding
! option values in some other command object. "Undefined" here means
! "is None", which is the convention used to indicate that an option
! has not been changed between 'initialize_options()' and
! 'finalize_options()'. Usually called from 'finalize_options()' for
! options that depend on some other command rather than another
! option of the same command. 'src_cmd' is the other command from
! which option values will be taken (a command object will be created
! for it if necessary); the remaining arguments are
! '(src_option,dst_option)' tuples which mean "take the value of
! 'src_option' in the 'src_cmd' command object, and copy it to
! 'dst_option' in the current command object".
! """
# Option_pairs: list of (src_option, dst_option) tuples
***************
*** 208,215 ****
def get_finalized_command (self, command, create=1):
! """Wrapper around Distribution's 'get_command_obj()' method:
! find (create if necessary and 'create' is true) the command
! object for 'command'.."""
!
cmd_obj = self.distribution.get_command_obj (command, create)
cmd_obj.ensure_finalized ()
--- 209,217 ----
def get_finalized_command (self, command, create=1):
! """Wrapper around Distribution's 'get_command_obj()' method: find
! (create if necessary and 'create' is true) the command object for
! 'command', call its 'ensure_finalized()' method, and return the
! finalized command object.
! """
cmd_obj = self.distribution.get_command_obj (command, create)
cmd_obj.ensure_finalized ()
***************
*** 223,229 ****
def run_command (self, command):
"""Run some other command: uses the 'run_command()' method of
! Distribution, which creates the command object if necessary
! and then invokes its 'run()' method."""
!
self.distribution.run_command (command)
--- 225,231 ----
def run_command (self, command):
"""Run some other command: uses the 'run_command()' method of
! Distribution, which creates and finalizes the command object if
! necessary and then invokes its 'run()' method.
! """
self.distribution.run_command (command)
***************
*** 237,249 ****
def execute (self, func, args, msg=None, level=1):
! """Perform some action that affects the outside world (eg.
! by writing to the filesystem). Such actions are special because
! they should be disabled by the "dry run" flag, and should
! announce themselves if the current verbosity level is high
! enough. This method takes care of all that bureaucracy for you;
! all you have to do is supply the funtion to call and an argument
! tuple for it (to embody the "external action" being performed),
! a message to print if the verbosity level is high enough, and an
! optional verbosity threshold."""
# Generate a message if we weren't passed one
--- 239,252 ----
def execute (self, func, args, msg=None, level=1):
! """Perform some action that affects the outside world (eg. by
! writing to the filesystem). Such actions are special because they
! should be disabled by the "dry run" flag, and should announce
! themselves if the current verbosity level is high enough. This
! method takes care of all that bureaucracy for you; all you have to
! do is supply the funtion to call and an argument tuple for it (to
! embody the "external action" being performed), a message to print
! if the verbosity level is high enough, and an optional verbosity
! threshold.
! """
# Generate a message if we weren't passed one
***************
*** 286,291 ****
level=1):
"""Copy an entire directory tree respecting verbose, dry-run,
! and force flags."""
!
return util.copy_tree (infile, outfile,
preserve_mode,preserve_times,preserve_symlinks,
--- 289,294 ----
level=1):
"""Copy an entire directory tree respecting verbose, dry-run,
! and force flags.
! """
return util.copy_tree (infile, outfile,
preserve_mode,preserve_times,preserve_symlinks,
***************
*** 303,306 ****
--- 306,310 ----
def spawn (self, cmd, search_path=1, level=1):
+ """Spawn an external command respecting verbose and dry-run flags."""
from distutils.spawn import spawn
spawn (cmd, search_path,
***************
*** 317,321 ****
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
more input files and generate one output file. Works just like
--- 321,324 ----
***************
*** 324,330 ****
files listed in 'infiles'. If the command defined 'self.force',
and it is true, then the command is unconditionally run -- does no
! timestamp checks."""
!
!
if exec_msg is None:
exec_msg = "generating %s from %s" % \
--- 327,332 ----
files listed in 'infiles'. If the command defined 'self.force',
and it is true, then the command is unconditionally run -- does no
! timestamp checks.
! """
if exec_msg is None:
exec_msg = "generating %s from %s" % \
Index: core.py
===================================================================
RCS file: /cvsroot/python/distutils/distutils/core.py,v
retrieving revision 1.38
retrieving revision 1.39
diff -C2 -r1.38 -r1.39
*** core.py 2000年05月31日 01:11:20 1.38
--- core.py 2000年06月02日 00:44:53 1.39
***************
*** 4,12 ****
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."""
# created 1999年03月01日, Greg Ward
! __revision__ = "$Id: core.py,v 1.38 2000年05月31日 01:11:20 gward Exp $"
import sys, os
--- 4,13 ----
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.
! """
# created 1999年03月01日, Greg Ward
! __revision__ = "$Id: core.py,v 1.39 2000年06月02日 00:44:53 gward Exp $"
import sys, os
***************
*** 38,71 ****
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."""
from pprint import pprint # for debugging output
--- 39,73 ----
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; 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