[Python-checkins] python/nondist/sandbox/distutilsref distref.tex,1.8,1.9
anthonybaxter@users.sourceforge.net
anthonybaxter@users.sourceforge.net
Mon, 26 May 2003 01:00:39 -0700
Update of /cvsroot/python/python/nondist/sandbox/distutilsref
In directory sc8-pr-cvs1:/tmp/cvs-serv7882
Modified Files:
distref.tex
Log Message:
doco for:
distutils.text_file
distutils.Command.sub_commands
Index: distref.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/distutilsref/distref.tex,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** distref.tex 22 May 2003 00:29:07 -0000 1.8
--- distref.tex 26 May 2003 08:00:36 -0000 1.9
***************
*** 1255,1261 ****
\modulesynopsis{provides the TextFile class, a simple interface to text files}
! This module provides the \class{TextFile} class, which gives an interface to text files
! that (optionally) takes care of stripping comments, ignoring blank
! lines, and joining lines with backslashes.
--- 1255,1372 ----
\modulesynopsis{provides the TextFile class, a simple interface to text files}
! This module provides the \class{TextFile} class, which gives an interface
! to text files that (optionally) takes care of stripping comments, ignoring
! blank lines, and joining lines with backslashes.
!
! \begin{classdesc}{TextFile}{\optional{filename=\code{None}, file=\code{None}, **options}}
! This class provides a file-like object that takes care of all
! the things you commonly want to do when processing a text file
! that has some line-by-line syntax: strip comments (as long as \code{#}
! is your comment character), skip blank lines, join adjacent lines by
! escaping the newline (ie. backslash at end of line), strip
! leading and/or trailing whitespace. All of these are optional
! and independently controllable.
!
! The class provides a \method{warn()} method so you can generate
! warning messages that report physical line number, even if the
! logical line in question spans multiple physical lines. Also
! provides \method{unreadline()} for implementing line-at-a-time lookahead.
!
! \class{TextFile} instances are create with either \var{filename}, \var{file},
! or both. \exception{RuntimeError} is raised if both are \code{None}.
! \var{filename} should be a string, and \var{file} a file object (or
! something that provides \method{readline()} and \method{close()}
! methods). It is recommended that you supply at least \var{filename},
! so that \class{TextFile} can include it in warning messages. If
! \var{file} is not supplied, TextFile creates its own using the
! \var{open()} builtin.
!
! The options are all boolean, and affect the values returned by
! \var{readline()}
!
! \begin{tableiii}{c|l|l}{option name}{option name}{description}{default}
! \lineiii{strip_comments}{
! strip from "\#" to end-of-line, as well as any whitespace
! leading up to the "\#" -- unless it is escaped by a backslash}
! {true}
! \lineiii{lstrip_ws}{
! strip leading whitespace from each line before returning it}
! {false}
! \lineiii{rstrip_ws}{
! strip trailing whitespace (including line terminator!) from
! each line before returning it.}
! {true}
! \lineiii{skip_blanks}{
! skip lines that are empty *after* stripping comments and
! whitespace. (If both lstrip_ws and rstrip_ws are false,
! then some lines may consist of solely whitespace: these will
! *not* be skipped, even if \var{skip_blanks} is true.)}
! {true}
! \lineiii{join_lines}{
! if a backslash is the last non-newline character on a line
! after stripping comments and whitespace, join the following line
! to it to form one "logical line"; if N consecutive lines end
! with a backslash, then N+1 physical lines will be joined to
! form one logical line.}
! {false}
! \lineiii{collapse_join}{
! strip leading whitespace from lines that are joined to their
! predecessor; only matters if \samp{(join_lines and not lstrip_ws)}}
! {false}
! \end{tableiii}
!
! Note that since \var{rstrip_ws} can strip the trailing newline, the
! semantics of \method{readline()} must differ from those of the builtin file
! object's \method{readline()} method! In particular, \method{readline()}
! returns \code{None} for end-of-file: an empty string might just be a
! blank line (or an all-whitespace line), if \var{rstrip_ws} is true
! but \var{skip_blanks} is not.
!
! \begin{methoddesc}{open}{filename}
! Open a new file \var{filename}. This overrides any \var{file} or
! \var{filename} constructor arguments.
! \end{methoddesc}
!
! \begin{methoddesc}{close}{}
! Close the current file and forget everything we know about it (including
! the filename and the current line number).
! \end{methoddesc}
!
! \begin{methoddesc}{warn}{msg\optional{,line=\code{None}}}
! Print (to stderr) a warning message tied to the current logical
! line in the current file. If the current logical line in the
! file spans multiple physical lines, the warning refers to the
! whole range, e.g. \samp{"lines 3-5"}. If \var{line} is supplied,
! it overrides the current line number; it may be a list or tuple
! to indicate a range of physical lines, or an integer for a
! single physical line.
! \end{methoddesc}
!
! \begin{methoddesc}{readline}{}
! Read and return a single logical line from the current file (or
! from an internal buffer if lines have previously been "unread"
! with \method{unreadline()}). If the \var{join_lines} option
! is true, this may involve reading multiple physical lines
! concatenated into a single string. Updates the current line number,
! so calling \method{warn()} after \method{readline()} emits a warning
! about the physical line(s) just read. Returns \code{None} on end-of-file,
! since the empty string can occur if \var{rstrip_ws} is true but
! \var{strip_blanks} is not.
! \end{methoddesc}
! \begin{methoddesc}{readlines}{}
! Read and return the list of all logical lines remaining in the current file.
! This updates the current line number to the last line of the file.
! \end{methoddesc}
! \begin{methoddesc}{unreadline}{line}
! Push \var{line} (a string) onto an internal buffer that will be
! checked by future \method{readline()} calls. Handy for implementing
! a parser with line-at-a-time lookahead. Note that lines that are "unread"
! with \method{unreadline} are not subsequently re-cleansed (whitespace
! stripped, or whatever) when read with \method{readline}. If multiple
! calls are made to \method{unreadline} before a call to \method{readline},
! the lines will be returned most in most recent first order.
! \end{methoddesc}
!
! \end{classdesc}
***************
*** 1267,1272 ****
This part of Distutils implements the various Distutils commands, such
! as 'build', 'install' \&c.
!
\subsubsection{\module{distutils.cmd} -- Abstract base class for Distutils commands}
--- 1378,1383 ----
This part of Distutils implements the various Distutils commands, such
! as \code{build}, \code{install} \&c. Each command is implemented as a
! separate module, with the command name as the name of the module.
\subsubsection{\module{distutils.cmd} -- Abstract base class for Distutils commands}
***************
*** 1296,1300 ****
\class{Distribution} instance.
-
\end{classdesc}
--- 1407,1410 ----
***************
*** 1411,1420 ****
\modulesynopsis{Register a module with the Python Package Index}
! The \code{register} command registers the package with the Python Package Index.
! This is described more in \pep{301}.
\subsubsection{Creating a new Distutils command}
! 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}
--- 1521,1530 ----
\modulesynopsis{Register a module with the Python Package Index}
! The \code{register} command registers the package with the Python Package
! Index. This is described in more detail in \pep{301}.
\subsubsection{Creating a new Distutils command}
! This section outlines the steps to create a new Distutils command.
A new command lives in a module in the \module{distutils.command}
***************
*** 1458,1460 ****
--- 1568,1585 ----
\end{methoddesc}
+ \var{sub_commands} formalizes the notion of a "family" of commands,
+ eg. \code{install} as the parent with sub-commands \code{install_lib},
+ \code{install_headers}, etc. The parent of a family of commands
+ defines \var{sub_commands} as a class attribute; it's a list of
+ 2-tuples \samp{(command_name, predicate)}, with \var{command_name} a string
+ and \var{predicate} an unbound method, a string or None.
+ \var{predicate} is a method of the parent command that
+ determines whether the corresponding command is applicable in the
+ current situation. (Eg. we \code{install_headers} is only applicable if
+ we have any C header files to install.) If \var{predicate} is None,
+ that command is always applicable.
+
+ \var{sub_commands} is usually defined at the *end* of a class, because
+ predicates can be unbound methods, so they must already have been
+ defined. The canonical example is the \code{install} command.