[Python-checkins] python/nondist/sandbox/distutilsref distref.tex,1.7,1.8

anthonybaxter@users.sourceforge.net anthonybaxter@users.sourceforge.net
Wed, 21 May 2003 17:29:10 -0700


Update of /cvsroot/python/python/nondist/sandbox/distutilsref
In directory sc8-pr-cvs1:/tmp/cvs-serv3552

Modified Files:
	distref.tex 
Log Message:
bit of fancy_getopt and the Command base class, as well as a start
at the "implementing new commands" section.


Index: distref.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/distutilsref/distref.tex,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** distref.tex	20 May 2003 08:42:03 -0000	1.7
--- distref.tex	22 May 2003 00:29:07 -0000	1.8
***************
*** 416,420 ****
  library file \var{lib} and return the full path to that file.  If
  \var{debug} is true, look for a debugging version (if that makes sense on
! the current platform).  Return None if \var{lib} wasn't found in any of
  the specified directories.
  \end{methoddesc}
--- 416,420 ----
  library file \var{lib} and return the full path to that file.  If
  \var{debug} is true, look for a debugging version (if that makes sense on
! the current platform).  Return \code{None} if \var{lib} wasn't found in any of
  the specified directories.
  \end{methoddesc}
***************
*** 486,490 ****
  \var{macros}, if given, must be a list of macro definitions.  A macro
  definition is either a \var{(name, value)} 2-tuple or a \var{(name,)} 1-tuple.
! The former defines a macro; if the value is None, the macro is
  defined without an explicit value.  The 1-tuple case undefines a
  macro.  Later definitions/redefinitions/undefinitions take
--- 486,490 ----
  \var{macros}, if given, must be a list of macro definitions.  A macro
  definition is either a \var{(name, value)} 2-tuple or a \var{(name,)} 1-tuple.
! The former defines a macro; if the value is \code{None}, the macro is
  defined without an explicit value.  The 1-tuple case undefines a
  macro.  Later definitions/redefinitions/undefinitions take
***************
*** 1138,1151 ****
  \modulesynopsis{Additional getopt functionality }
  
! This module provides a wrapper around the standard \refmodule{getopt} module that 
! provides the following
! additional features:
  \begin{itemize}
  \item short and long options are tied together
! \item options have help strings, so fancy_getopt could potentially create a complete usage summary
  \item options set attributes of a passed-in object
  \end{itemize}
  
! \warning{Should be replaced with optik (which is also now known as \refmodule{optparse})}
  
  \subsubsection{\module{distutils.filelist} -- The FileList class}
--- 1138,1212 ----
  \modulesynopsis{Additional getopt functionality }
  
! This module provides a wrapper around the standard \refmodule{getopt} 
! module that provides the following additional features:
! 
  \begin{itemize}
  \item short and long options are tied together
! \item options have help strings, so \function{fancy_getopt} could potentially 
! create a complete usage summary
  \item options set attributes of a passed-in object
+ \item boolean options can have "negative aliases" -- eg. if \code{--quiet} 
+ is the "negative alias" of \code{--verbose}, then \code{--quiet} on the 
+ command line sets \var{verbose} to false
+ 
  \end{itemize}
  
! \warning{Should be replaced with \module{optik} (which is also now known as \refmodule{optparse} in Python 2.3 and later).}
! 
! \begin{funcdesc}{fancy_getopt}{options, negative_opt, object, args}
! Wrapper function. \var{options} is a list of 
! \samp{(long_option, short_option, help_string)} 3-tuples as described in the
! constructor for \class{FancyGetopt}. \var{negative_opt} should be a dictionary
! mapping option names to option names, both the key and value should be in the
! \var{options} list. \var{object} is an object which will be used to store
! values (see the \method{getopt} method of the \class{FancyGetopt} class).
! \var{args} is the argument list. Will use \code{sys.argv[1:]} if you 
! pass \code{None} as \var{args}.
! \end{funcdesc}
! 
! \begin{funcdesc}{wrap_text}{text, width}
! Wraps \var{text} to less than \var{width} wide.
! 
! \warning{Should be replaced with \refmodule{textwrap} (which is available 
! in Python 2.3 and later).}
! \end{funcdesc}
! 
! \begin{classdesc}{FancyGetopt}{\optional{option_table=\code{None}}}
! 
! The option_table is a list of 3-tuples: 
! \samp{(long_option, short_option, help_string)}
! 
! If an option takes an argument, it's \var{long_option} should have \code{'='}
! appended; \var{short_option} should just be a single character, no \code{':'}
! in any case. \var{short_option} should be \code{None} if a \var{long_option} 
! doesn't have a corresponding \var{short_option}. All option tuples must have
! long options.
! 
! \begin{methoddesc}{getopt}{\optional{args=\code{None}, object=\code{None}}}
! Parse command-line options in args. Store as attributes on \var{object}.
! 
! If \var{args} is \code{None} or not supplied, uses \code{sys.argv[1:]}.  If
! \var{object} is \code{None} or not supplied, creates a new \class{OptionDummy}
! instance, stores option values there, and returns a tuple \samp{(args,
! object)}.  If \var{object} is supplied, it is modified in place and
! \function{getopt()} just returns \var{args}; in both cases, the returned
! \var{args} is a modified copy of the passed-in \var{args} list, which
! is left untouched.
! % and args returned are?
! \end{methoddesc}
! 
! \begin{methoddesc}{get_option_order}{}
! Returns the list of \samp{(option, value)} tuples processed by the
! previous run of \method{getopt()}  Raises \exception{RuntimeError} if
! \method{getopt()} hasn't been called yet.
! \end{methoddesc}
! 
! \begin{methoddesc}{generate_help}{\optional{header=\code{None}}}
! Generate help text (a list of strings, one per suggested line of
! output) from the option table for this \class{FancyGetopt} object.
! 
! If supplied, prints the supplied \var{header} at the top of the help.
! \end{methoddesc}
! \end{classdesc}
  
  \subsubsection{\module{distutils.filelist} -- The FileList class}
***************
*** 1215,1218 ****
--- 1276,1302 ----
  subpackage. }
  
+ This module supplies the abstract base class \class{Command}. 
+ 
+ \begin{classdesc}{Command}{dist}
+ 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 \var{options}.  The options
+ are "declared" in \method{initialize_options()} and "defined" (given their
+ final values, aka "finalized") in \method{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 \method{finalize_options()}.  The "body" of the
+ subroutine, where it does all its work based on the values of its
+ options, is the \method{run()} method, which must also be implemented by every
+ command class.
+ 
+ The class constructor takes a single argument \var{dist}, a 
+ \class{Distribution} instance. 
+ 
+ 
+ \end{classdesc}
+ 
  
  \subsubsection{\module{distutils.command} -- Individual Distutils commands}
***************
*** 1333,1335 ****
--- 1417,1460 ----
  
  This section will go through the steps to create a new Distutils command.
+ 
+ A new command lives in a module in the \module{distutils.command}
+ package. There is a sample template in that directory called 
+ \file{command_template}. Copy this file to a new module with the
+ same name as the new command you're implementing. This module should
+ implement a class with the same name as the module (and the command).
+ So, for instance, to create the command \code{peel_banana} (so that users
+ can run \samp{setup.py peel_banana}), you'd copy \file{command_template} 
+ to \file{distutils/command/peel_banana.py}, then edit it so that it's
+ implementing the class \class{peel_banana}, a subclass of 
+ \class{distutils.cmd.Command}.
+ 
+ Subclasses of \class{Command} must define the following methods.
+ 
+ \begin{methoddesc}{initialize_options()}
+ 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, \method{initialize_options()} implementations
+ are just a bunch of \samp{self.foo = None} assignments.
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{finalize_options}{}
+ 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
+ \var{foo} depends on \var{bar}, then it is safe to set \var{foo} from 
+ \var{bar} as long as \var{foo} still has the same value it was assigned in
+ \method{initialize_options()}.
+ \end{methoddesc}
+ \begin{methoddesc}{run}{}
+ A command's raison d'etre: carry out the action it exists to
+ perform, controlled by the options initialized in
+ \method{initialize_options()}, customized by other commands, the setup
+ script, the command-line, and config files, and finalized in
+ \method{finalize_options()}.  All terminal output and filesystem
+ interaction should be done by \method{run()}.
+ \end{methoddesc}
+