mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 02:39:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

Reformatted and updated many docstrings.

Browse source
This commit is contained in:
Greg Ward 2000-06-02 00:44:53 +00:00
parent 4c7fdfc35b
commit 8ff5a3fd92
3 changed files with 135 additions and 134 deletions
Download patch file Download diff file Expand all files Collapse all files

166
Lib/distutils/cmd.py
View file

@ -1,7 +1,8 @@
"""distutils.cmd """distutils.cmd
Provides the Command class, the base class for the command classes Provides the Command class, the base class for the command classes
in the distutils.command package.""" in the distutils.command package.
"""
# created 2000/04/03, Greg Ward # created 2000/04/03, Greg Ward
# (extricated from core.py; actually dates back to the beginning) # (extricated from core.py; actually dates back to the beginning)
@ -16,28 +17,28 @@ from distutils import util
class Command: class Command:
"""Abstract base class for defining command classes, the "worker bees" """Abstract base class for defining command classes, the "worker bees"
of the Distutils. A useful analogy for command classes is to of the Distutils. A useful analogy for command classes is to think of
think of them as subroutines with local variables called them as subroutines with local variables called "options". The options
"options". The options are "declared" in 'initialize_options()' are "declared" in 'initialize_options()' and "defined" (given their
and "defined" (given their final values, aka "finalized") in final values, aka "finalized") in 'finalize_options()', both of which
'finalize_options()', both of which must be defined by every must be defined by every command class. The distinction between the
command class. The distinction between the two is necessary two is necessary because option values might come from the outside
because option values might come from the outside world (command world (command line, config file, ...), and any options dependent on
line, option file, ...), and any options dependent on other other options must be computed *after* these outside influences have
options must be computed *after* these outside influences have been processed -- hence 'finalize_options()'. The "body" of the
been processed -- hence 'finalize_options()'. The "body" of the subroutine, where it does all its work based on the values of its
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
options, is the 'run()' method, which must also be implemented by command class.
every command class.""" """
# -- Creation/initialization methods ------------------------------- # -- Creation/initialization methods -------------------------------
def __init__ (self, dist): def __init__ (self, dist):
"""Create and initialize a new Command object. Most importantly, """Create and initialize a new Command object. Most importantly,
invokes the 'initialize_options()' method, which is the invokes the 'initialize_options()' method, which is the real
real initializer and depends on the actual command being initializer and depends on the actual command being
instantiated.""" instantiated.
"""
# late import because of mutual dependence between these classes # late import because of mutual dependence between these classes
from distutils.dist import Distribution from distutils.dist import Distribution
@ -97,9 +98,9 @@ class Command:
# Subclasses must define: # Subclasses must define:
# initialize_options() # initialize_options()
# provide default values for all options; may be overridden # provide default values for all options; may be customized by
# by Distutils client, by command-line options, or by options # setup script, by options from config file(s), or by command-line
# from option file # options
# finalize_options() # finalize_options()
# decide on the final values for all options; this is called # decide on the final values for all options; this is called
# after all possible intervention from the outside world # after all possible intervention from the outside world
@ -110,28 +111,28 @@ class Command:
def initialize_options (self): def initialize_options (self):
"""Set default values for all the options that this command """Set default values for all the options that this command
supports. Note that these defaults may be overridden supports. Note that these defaults may be overridden by other
by the command-line supplied by the user; thus, this is commands, by the setup script, by config files, or by the
not the place to code dependencies between options; generally, command-line. Thus, this is not the place to code dependencies
'initialize_options()' implementations are just a bunch between options; generally, 'initialize_options()' implementations
of "self.foo = None" assignments. are just a bunch of "self.foo = None" assignments.
This method must be implemented by all command classes."""
This method must be implemented by all command classes.
"""
raise RuntimeError, \ raise RuntimeError, \
"abstract method -- subclass %s must override" % self.__class__ "abstract method -- subclass %s must override" % self.__class__
def finalize_options (self): def finalize_options (self):
"""Set final values for all the options that this command """Set final values for all the options that this command supports.
supports. This is always called as late as possible, ie. This is always called as late as possible, ie. after any option
after any option assignments from the command-line or from assignments from the command-line or from other commands have been
other commands have been done. Thus, this is the place to to done. Thus, this is the place to to code option dependencies: if
code option dependencies: if 'foo' depends on 'bar', then it 'foo' depends on 'bar', then it is safe to set 'foo' from 'bar' as
is safe to set 'foo' from 'bar' as long as 'foo' still has long as 'foo' still has the same value it was assigned in
the same value it was assigned in 'initialize_options()'. 'initialize_options()'.
This method must be implemented by all command classes."""
This method must be implemented by all command classes.
"""
raise RuntimeError, \ raise RuntimeError, \
"abstract method -- subclass %s must override" % self.__class__ "abstract method -- subclass %s must override" % self.__class__
@ -151,23 +152,23 @@ class Command:
def run (self): def run (self):
"""A command's raison d'etre: carry out the action it exists """A command's raison d'etre: carry out the action it exists to
to perform, controlled by the options initialized in perform, controlled by the options initialized in
'initialize_options()', customized by the user and other 'initialize_options()', customized by other commands, the setup
commands, and finalized in 'finalize_options()'. All script, the command-line, and config files, and finalized in
terminal output and filesystem interaction should be done by 'finalize_options()'. All terminal output and filesystem
'run()'. interaction should be done by 'run()'.
This method must be implemented by all command classes.""" This method must be implemented by all command classes.
"""
raise RuntimeError, \ raise RuntimeError, \
"abstract method -- subclass %s must override" % self.__class__ "abstract method -- subclass %s must override" % self.__class__
def announce (self, msg, level=1): def announce (self, msg, level=1):
"""If the Distribution instance to which this command belongs """If the current verbosity level is of greater than or equal to
has a verbosity level of greater than or equal to 'level' 'level' print 'msg' to stdout.
print 'msg' to stdout.""" """
if self.verbose >= level: if self.verbose >= level:
print msg print msg
@ -183,18 +184,18 @@ class Command:
def set_undefined_options (self, src_cmd, *option_pairs): def set_undefined_options (self, src_cmd, *option_pairs):
"""Set the values of any "undefined" options from corresponding """Set the values of any "undefined" options from corresponding
option values in some other command object. "Undefined" here option values in some other command object. "Undefined" here means
means "is None", which is the convention used to indicate "is None", which is the convention used to indicate that an option
that an option has not been changed between has not been changed between 'initialize_options()' and
'set_initial_values()' and 'set_final_values()'. Usually 'finalize_options()'. Usually called from 'finalize_options()' for
called from 'set_final_values()' for options that depend on options that depend on some other command rather than another
some other command rather than another option of the same option of the same command. 'src_cmd' is the other command from
command. 'src_cmd' is the other command from which option which option values will be taken (a command object will be created
values will be taken (a command object will be created for it for it if necessary); the remaining arguments are
if necessary); the remaining arguments are '(src_option,dst_option)' tuples which mean "take the value of
'(src_option,dst_option)' tuples which mean "take the value 'src_option' in the 'src_cmd' command object, and copy it to
of 'src_option' in the 'src_cmd' command object, and copy it 'dst_option' in the current command object".
to 'dst_option' in the current command object".""" """
# Option_pairs: list of (src_option, dst_option) tuples # Option_pairs: list of (src_option, dst_option) tuples
@ -207,10 +208,11 @@ class Command:
def get_finalized_command (self, command, create=1): def get_finalized_command (self, command, create=1):
"""Wrapper around Distribution's 'get_command_obj()' method: """Wrapper around Distribution's 'get_command_obj()' method: find
find (create if necessary and 'create' is true) the command (create if necessary and 'create' is true) the command object for
object for 'command'..""" 'command', call its 'ensure_finalized()' method, and return the
finalized command object.
"""
cmd_obj = self.distribution.get_command_obj (command, create) cmd_obj = self.distribution.get_command_obj (command, create)
cmd_obj.ensure_finalized () cmd_obj.ensure_finalized ()
return cmd_obj return cmd_obj
@ -222,9 +224,9 @@ class Command:
def run_command (self, command): def run_command (self, command):
"""Run some other command: uses the 'run_command()' method of """Run some other command: uses the 'run_command()' method of
Distribution, which creates the command object if necessary Distribution, which creates and finalizes the command object if
and then invokes its 'run()' method.""" necessary and then invokes its 'run()' method.
"""
self.distribution.run_command (command) self.distribution.run_command (command)
@ -236,15 +238,16 @@ class Command:
def execute (self, func, args, msg=None, level=1): def execute (self, func, args, msg=None, level=1):
"""Perform some action that affects the outside world (eg. """Perform some action that affects the outside world (eg. by
by writing to the filesystem). Such actions are special because writing to the filesystem). Such actions are special because they
they should be disabled by the "dry run" flag, and should should be disabled by the "dry run" flag, and should announce
announce themselves if the current verbosity level is high themselves if the current verbosity level is high enough. This
enough. This method takes care of all that bureaucracy for you; method takes care of all that bureaucracy for you; all you have to
all you have to do is supply the funtion to call and an argument do is supply the funtion to call and an argument tuple for it (to
tuple for it (to embody the "external action" being performed), embody the "external action" being performed), a message to print
a message to print if the verbosity level is high enough, and an if the verbosity level is high enough, and an optional verbosity
optional verbosity threshold.""" threshold.
"""
# Generate a message if we weren't passed one # Generate a message if we weren't passed one
if msg is None: if msg is None:
@ -285,8 +288,8 @@ class Command:
preserve_mode=1, preserve_times=1, preserve_symlinks=0, preserve_mode=1, preserve_times=1, preserve_symlinks=0,
level=1): level=1):
"""Copy an entire directory tree respecting verbose, dry-run, """Copy an entire directory tree respecting verbose, dry-run,
and force flags.""" and force flags.
"""
return util.copy_tree (infile, outfile, return util.copy_tree (infile, outfile,
preserve_mode,preserve_times,preserve_symlinks, preserve_mode,preserve_times,preserve_symlinks,
not self.force, not self.force,
@ -302,6 +305,7 @@ class Command:
def spawn (self, cmd, search_path=1, level=1): def spawn (self, cmd, search_path=1, level=1):
"""Spawn an external command respecting verbose and dry-run flags."""
from distutils.spawn import spawn from distutils.spawn import spawn
spawn (cmd, search_path, spawn (cmd, search_path,
self.verbose >= level, self.verbose >= level,
@ -316,16 +320,14 @@ class Command:
def make_file (self, infiles, outfile, func, args, def make_file (self, infiles, outfile, func, args,
exec_msg=None, skip_msg=None, level=1): exec_msg=None, skip_msg=None, level=1):
"""Special case of 'execute()' for operations that process one or """Special case of 'execute()' for operations that process one or
more input files and generate one output file. Works just like more input files and generate one output file. Works just like
'execute()', except the operation is skipped and a different 'execute()', except the operation is skipped and a different
message printed if 'outfile' already exists and is newer than all message printed if 'outfile' already exists and is newer than all
files listed in 'infiles'. If the command defined 'self.force', files listed in 'infiles'. If the command defined 'self.force',
and it is true, then the command is unconditionally run -- does no and it is true, then the command is unconditionally run -- does no
timestamp checks.""" timestamp checks.
"""
if exec_msg is None: if exec_msg is None:
exec_msg = "generating %s from %s" % \ exec_msg = "generating %s from %s" % \
(outfile, string.join (infiles, ', ')) (outfile, string.join (infiles, ', '))

58
Lib/distutils/core.py
View file

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

45
Lib/distutils/dist.py
View file

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