add hg and python

1 files changed, 313 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libcfgparser.tex b/sys/src/cmd/python/Doc/lib/libcfgparser.tex
new file mode 100644
index 000000000..42a362eac
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libcfgparser.tex
@@ -0,0 +1,313 @@
+\section{\module{ConfigParser} ---
+         Configuration file parser}
+
+\declaremodule{standard}{ConfigParser}
+\modulesynopsis{Configuration file parser.}
+\moduleauthor{Ken Manheimer}{klm@zope.com}
+\moduleauthor{Barry Warsaw}{bwarsaw@python.org}
+\moduleauthor{Eric S. Raymond}{esr@thyrsus.com}
+\sectionauthor{Christopher G. Petrilli}{petrilli@amber.org}
+
+This module defines the class \class{ConfigParser}.
+\indexii{.ini}{file}\indexii{configuration}{file}\index{ini file}
+\index{Windows ini file}
+The \class{ConfigParser} class implements a basic configuration file
+parser language which provides a structure similar to what you would
+find on Microsoft Windows INI files.  You can use this to write Python
+programs which can be customized by end users easily.
+
+\begin{notice}[warning]
+  This library does \emph{not} interpret or write the value-type
+  prefixes used in the Windows Registry extended version of INI syntax.
+\end{notice}
+
+The configuration file consists of sections, led by a
+\samp{[section]} header and followed by \samp{name: value} entries,
+with continuations in the style of \rfc{822}; \samp{name=value} is
+also accepted.  Note that leading whitespace is removed from values.
+The optional values can contain format strings which refer to other
+values in the same section, or values in a special
+\code{DEFAULT} section.  Additional defaults can be provided on
+initialization and retrieval.  Lines beginning with \character{\#} or
+\character{;} are ignored and may be used to provide comments.
+
+For example:
+
+\begin{verbatim}
+[My Section]
+foodir: %(dir)s/whatever
+dir=frob
+\end{verbatim}
+
+would resolve the \samp{\%(dir)s} to the value of
+\samp{dir} (\samp{frob} in this case).  All reference expansions are
+done on demand.
+
+Default values can be specified by passing them into the
+\class{ConfigParser} constructor as a dictionary.  Additional defaults 
+may be passed into the \method{get()} method which will override all
+others.
+
+\begin{classdesc}{RawConfigParser}{\optional{defaults}}
+The basic configuration object.  When \var{defaults} is given, it is
+initialized into the dictionary of intrinsic defaults.  This class
+does not support the magical interpolation behavior.
+\versionadded{2.3}
+\end{classdesc}
+
+\begin{classdesc}{ConfigParser}{\optional{defaults}}
+Derived class of \class{RawConfigParser} that implements the magical
+interpolation feature and adds optional arguments to the \method{get()}
+and \method{items()} methods.  The values in \var{defaults} must be
+appropriate for the \samp{\%()s} string interpolation.  Note that
+\var{__name__} is an intrinsic default; its value is the section name,
+and will override any value provided in \var{defaults}.
+
+All option names used in interpolation will be passed through the
+\method{optionxform()} method just like any other option name
+reference.  For example, using the default implementation of
+\method{optionxform()} (which converts option names to lower case),
+the values \samp{foo \%(bar)s} and \samp{foo \%(BAR)s} are
+equivalent.
+\end{classdesc}
+
+\begin{classdesc}{SafeConfigParser}{\optional{defaults}}
+Derived class of \class{ConfigParser} that implements a more-sane
+variant of the magical interpolation feature.  This implementation is
+more predictable as well.
+% XXX Need to explain what's safer/more predictable about it.
+New applications should prefer this version if they don't need to be
+compatible with older versions of Python.
+\versionadded{2.3}
+\end{classdesc}
+
+\begin{excdesc}{NoSectionError}
+Exception raised when a specified section is not found.
+\end{excdesc}
+
+\begin{excdesc}{DuplicateSectionError}
+Exception raised if \method{add_section()} is called with the name of
+a section that is already present.
+\end{excdesc}
+
+\begin{excdesc}{NoOptionError}
+Exception raised when a specified option is not found in the specified 
+section.
+\end{excdesc}
+
+\begin{excdesc}{InterpolationError}
+Base class for exceptions raised when problems occur performing string
+interpolation.
+\end{excdesc}
+
+\begin{excdesc}{InterpolationDepthError}
+Exception raised when string interpolation cannot be completed because
+the number of iterations exceeds \constant{MAX_INTERPOLATION_DEPTH}.
+Subclass of \exception{InterpolationError}.
+\end{excdesc}
+
+\begin{excdesc}{InterpolationMissingOptionError}
+Exception raised when an option referenced from a value does not exist.
+Subclass of \exception{InterpolationError}.
+\versionadded{2.3}
+\end{excdesc}
+
+\begin{excdesc}{InterpolationSyntaxError}
+Exception raised when the source text into which substitutions are
+made does not conform to the required syntax.
+Subclass of \exception{InterpolationError}.
+\versionadded{2.3}
+\end{excdesc}
+
+\begin{excdesc}{MissingSectionHeaderError}
+Exception raised when attempting to parse a file which has no section
+headers.
+\end{excdesc}
+
+\begin{excdesc}{ParsingError}
+Exception raised when errors occur attempting to parse a file.
+\end{excdesc}
+
+\begin{datadesc}{MAX_INTERPOLATION_DEPTH}
+The maximum depth for recursive interpolation for \method{get()} when
+the \var{raw} parameter is false.  This is relevant only for the
+\class{ConfigParser} class.
+\end{datadesc}
+
+
+\begin{seealso}
+  \seemodule{shlex}{Support for a creating \UNIX{} shell-like
+                    mini-languages which can be used as an alternate
+                    format for application configuration files.}
+\end{seealso}
+
+
+\subsection{RawConfigParser Objects \label{RawConfigParser-objects}}
+
+\class{RawConfigParser} instances have the following methods:
+
+\begin{methoddesc}{defaults}{}
+Return a dictionary containing the instance-wide defaults.
+\end{methoddesc}
+
+\begin{methoddesc}{sections}{}
+Return a list of the sections available; \code{DEFAULT} is not
+included in the list.
+\end{methoddesc}
+
+\begin{methoddesc}{add_section}{section}
+Add a section named \var{section} to the instance.  If a section by
+the given name already exists, \exception{DuplicateSectionError} is
+raised.
+\end{methoddesc}
+
+\begin{methoddesc}{has_section}{section}
+Indicates whether the named section is present in the
+configuration. The \code{DEFAULT} section is not acknowledged.
+\end{methoddesc}
+
+\begin{methoddesc}{options}{section}
+Returns a list of options available in the specified \var{section}.
+\end{methoddesc}
+
+\begin{methoddesc}{has_option}{section, option}
+If the given section exists, and contains the given option,
+return \constant{True}; otherwise return \constant{False}.
+\versionadded{1.6}
+\end{methoddesc}
+
+\begin{methoddesc}{read}{filenames}
+Attempt to read and parse a list of filenames, returning a list of filenames
+which were successfully parsed.  If \var{filenames} is a string or
+Unicode string, it is treated as a single filename.
+If a file named in \var{filenames} cannot be opened, that file will be
+ignored.  This is designed so that you can specify a list of potential
+configuration file locations (for example, the current directory, the
+user's home directory, and some system-wide directory), and all
+existing configuration files in the list will be read.  If none of the
+named files exist, the \class{ConfigParser} instance will contain an
+empty dataset.  An application which requires initial values to be
+loaded from a file should load the required file or files using
+\method{readfp()} before calling \method{read()} for any optional
+files:
+
+\begin{verbatim}
+import ConfigParser, os
+
+config = ConfigParser.ConfigParser()
+config.readfp(open('defaults.cfg'))
+config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
+\end{verbatim}
+\versionchanged[Returns list of successfully parsed filenames]{2.4}
+\end{methoddesc}
+
+\begin{methoddesc}{readfp}{fp\optional{, filename}}
+Read and parse configuration data from the file or file-like object in
+\var{fp} (only the \method{readline()} method is used).  If
+\var{filename} is omitted and \var{fp} has a \member{name} attribute,
+that is used for \var{filename}; the default is \samp{<???>}.
+\end{methoddesc}
+
+\begin{methoddesc}{get}{section, option}
+Get an \var{option} value for the named \var{section}.
+\end{methoddesc}
+
+\begin{methoddesc}{getint}{section, option}
+A convenience method which coerces the \var{option} in the specified
+\var{section} to an integer.
+\end{methoddesc}
+
+\begin{methoddesc}{getfloat}{section, option}
+A convenience method which coerces the \var{option} in the specified
+\var{section} to a floating point number.
+\end{methoddesc}
+
+\begin{methoddesc}{getboolean}{section, option}
+A convenience method which coerces the \var{option} in the specified
+\var{section} to a Boolean value.  Note that the accepted values
+for the option are \code{"1"}, \code{"yes"}, \code{"true"}, and \code{"on"},
+which cause this method to return \code{True}, and \code{"0"}, \code{"no"},
+\code{"false"}, and \code{"off"}, which cause it to return \code{False}.  These
+string values are checked in a case-insensitive manner.  Any other value will
+cause it to raise \exception{ValueError}.
+\end{methoddesc}
+
+\begin{methoddesc}{items}{section}
+Return a list of \code{(\var{name}, \var{value})} pairs for each
+option in the given \var{section}.
+\end{methoddesc}
+
+\begin{methoddesc}{set}{section, option, value}
+If the given section exists, set the given option to the specified
+value; otherwise raise \exception{NoSectionError}.  While it is
+possible to use \class{RawConfigParser} (or \class{ConfigParser} with
+\var{raw} parameters set to true) for \emph{internal} storage of
+non-string values, full functionality (including interpolation and
+output to files) can only be achieved using string values.
+\versionadded{1.6}
+\end{methoddesc}
+
+\begin{methoddesc}{write}{fileobject}
+Write a representation of the configuration to the specified file
+object.  This representation can be parsed by a future \method{read()}
+call.
+\versionadded{1.6}
+\end{methoddesc}
+
+\begin{methoddesc}{remove_option}{section, option}
+Remove the specified \var{option} from the specified \var{section}.
+If the section does not exist, raise \exception{NoSectionError}. 
+If the option existed to be removed, return \constant{True};
+otherwise return \constant{False}.
+\versionadded{1.6}
+\end{methoddesc}
+
+\begin{methoddesc}{remove_section}{section}
+Remove the specified \var{section} from the configuration.
+If the section in fact existed, return \code{True}.
+Otherwise return \code{False}.
+\end{methoddesc}
+
+\begin{methoddesc}{optionxform}{option}
+Transforms the option name \var{option} as found in an input file or
+as passed in by  client code to the form that should be used in the
+internal structures.  The default implementation returns a lower-case
+version of \var{option}; subclasses may override this or client code
+can set an attribute of this name on instances to affect this
+behavior.  Setting this to \function{str()}, for example, would make
+option names case sensitive.
+\end{methoddesc}
+
+
+\subsection{ConfigParser Objects \label{ConfigParser-objects}}
+
+The \class{ConfigParser} class extends some methods of the
+\class{RawConfigParser} interface, adding some optional arguments.
+
+\begin{methoddesc}{get}{section, option\optional{, raw\optional{, vars}}}
+Get an \var{option} value for the named \var{section}.  All the
+\character{\%} interpolations are expanded in the return values, based
+on the defaults passed into the constructor, as well as the options
+\var{vars} provided, unless the \var{raw} argument is true.
+\end{methoddesc}
+
+\begin{methoddesc}{items}{section\optional{, raw\optional{, vars}}}
+Return a list of \code{(\var{name}, \var{value})} pairs for each
+option in the given \var{section}. Optional arguments have the
+same meaning as for the \method{get()} method.
+\versionadded{2.3}
+\end{methoddesc}
+
+
+\subsection{SafeConfigParser Objects \label{SafeConfigParser-objects}}
+
+The \class{SafeConfigParser} class implements the same extended
+interface as \class{ConfigParser}, with the following addition:
+
+\begin{methoddesc}{set}{section, option, value}
+If the given section exists, set the given option to the specified
+value; otherwise raise \exception{NoSectionError}.  \var{value} must
+be a string (\class{str} or \class{unicode}); if not,
+\exception{TypeError} is raised.
+\versionadded{2.4}
+\end{methoddesc}