[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}
+