[Zope3-checkins] CVS: Zope/lib/python/ZConfig/doc - oldapi.tex:1.1

[Fred L. Drake, Jr.]

Update of /cvs-repository/Zope/lib/python/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv16965

Added Files:
	oldapi.tex 
Log Message:
New location for documentation of legacy API.

=== Added File Zope/lib/python/ZConfig/doc/oldapi.tex ===
% The modules described here have been left in the package while
% client code is updated to use the schema-based configurations.

\section{\module{ZConfig.Context} --- Application context (obsolete)}

\declaremodule{}{ZConfig.Context}
\modulesynopsis{Application context.}

\begin{notice}[warning]
  This module is provided for backward compatibility.  It may be
  removed at some point in the future.  The configuration objects
  returned by methods of the \class{Context} object described here are
  very different from the schema-based configuration objects.
\end{notice}

The \module{ZConfig} package uses the idea of an \dfn{application
context} to consolidate the connections between the different
components of the package.  Most applications should be able to use
the context implementation provided in this module.

For applications that need to change the way their configuration data
is handled, the best way to do it is to provide an alternate
application context.  The default implementation is designed to be
subclassed, so this should not prove to be difficult.

\begin{classdesc}{Context}{}
  Constructs an instance of the default application context.  This is
  implemented as an object to allow applications to adjust the way
  components are created and how they are knit together.  This
  implementation is designed to be used once and discarded; changing
  this assumption in a subclass would probably lead to a complete
  replacement of the class.
\end{classdesc}

The context object offers two methods that are used to load a
configuration.  Exactly one of these methods should be called, and it
should be called only once:

\begin{methoddesc}{loadURL}{url}
  Load and return a configuration object from a resource.  The
  resource is identified by a URL or path given as \var{url}.
  Fragment identifiers are not supported.
\end{methoddesc}

\begin{methoddesc}{loadFile}{file\optional{, url}}
  Load and return a configuration from an opened file object.
  If \var{url} is omitted, one will be computed based on the
  \member{name} attribute of \var{file}, if it exists.  If no URL can
  be determined, all \keyword{\%include} statements in the configuration
  must use absolute URLs.
\end{methoddesc}

The following methods are defined to be individually overridden by
subclasses; this should suffice for most context specialization.

\begin{methoddesc}{createNestedSection}{parent, type, name, delegatename}
  Create a new section that represents a child of the section given by
  \var{parent}.  \var{type} is the type that should be given to the
  new section and should always be a string.  \var{name} should be the
  name of the section, and should be a string or \code{None}.
  \var{delegatename} should also be a string or \code{None}; if not
  \code{None}, this will be the name of the section eventually passed
  to the \method{setDelegate()} method of the returned section.  The
  returned section should be conform to the interface of the
  \class{Configuration} class (see the \refmodule{ZConfig.Config}
  module's documentation for more information on this interface).
\end{methoddesc}

\begin{methoddesc}{createToplevelSection}{url}
  Create a new section that represents a section loaded and returned
  by the \method{loadURL()} method of the context object.  The returned
  section should be conform to the interface of the
  \class{ImportingConfiguration} class (see the
  \refmodule{ZConfig.Config} module's documentation for more
  information on this interface).  \var{url} is the resource that will
  be loaded into the new section.
  Since the new section represents the top level of an external
  resource, it's \member{type} and \member{name} attributes should be
  \code{None}.
\end{methoddesc}

\begin{methoddesc}{getDelegateType}{type}
  Return the type of sections to which sections of type \var{type} may
  delegate to, or \code{None} if they are not allowed to do so.
\end{methoddesc}

\begin{methoddesc}{parse}{resource, section}
  This method allows subclasses to replace the resource parser.
  \var{resource} is an object that represents a configuration source;
  it has two attributes, \member{file} and \member{url}.  The
  \member{file} attribute is a file object which provides the content
  of the resource, and \member{url} is the URL from which the resource
  is being loaded.  \var{section} is the section object into which the
  contents of the resources should be loaded.  The default
  implementation implements the configuration language described in
  section~\ref{syntax}.  Providing an
  alternate parser is most easily done by overriding this method and
  calling the parser support methods of the context object from the
  new parser, though different strategies are possible.
\end{methoddesc}

The following methods are provided to make it easy for parsers to
support common semantics for the \keyword{\%include} statement, if
that is defined for the syntax implemented by the alternate parser.

\begin{methoddesc}{includeConfiguration}{parent, url}
\end{methoddesc}

\begin{methoddesc}{startSection}{parent, type, name, delegatename}
\end{methoddesc}

\begin{methoddesc}{endSection}{parent, type, name, delegatename, section}
\end{methoddesc}


\section{\module{ZConfig.Config} --- Section objects (obsolete)}

\declaremodule{}{ZConfig.Config}
\modulesynopsis{Standard section objects.}


\begin{notice}[warning]
  This module is provided for backward compatibility.  It may be
  removed at some point in the future.  It should really be considered
  an implementation detail of the configuration objects returned by
  methods of the \class{Context} object defined in the
  \refmodule{ZConfig.Context} module.
\end{notice}

The \module{ZConfig.Config} module provides an implementation of the
standard key-value section for configurations loaded by the
\module{ZConfig.Context} module.

\begin{classdesc}{Configuration}{type, name, url}
  A typed section with an optional name.  The type is given by the
  \var{type} argument, and the URL the configuration is loaded from is
  given by \var{url}.  Both \var{type} and \var{url} must be strings.
  The optional name of the section is given by \var{name}; if there is
  no name, \var{name} should be \code{None}.
\end{classdesc}

\class{Configuration} objects provide the following attributes and
methods to retrieve information from the section:

\begin{memberdesc}[Configuration]{container}
  The containing section of this section, or \code{None}.
\end{memberdesc}

\begin{memberdesc}[Configuration]{delegate}
  The \class{Configuration} object to which lookups are delegated when
  they cannot be satisfied directly.  If there is no such section,
  this will be \code{None}.
\end{memberdesc}

\begin{methoddesc}[Configuration]{get}{key\optional{, default}}
  Returns the value for \var{key} as a string; a value from the
  delegate section is used if needed.  If there is no value for
  \var{key}, returns \var{default}.
\end{methoddesc}

\begin{methoddesc}[Configuration]{getbool}{key\optional{, default}}
  Returns the value for \var{key} as a \class{bool}.  If there is no
  value for \var{key}, returns \var{default}.  Conversions to
  \class{bool} are case-insensitive; the strings \code{true},
  \code{yes}, and \code{on} cause \code{True} to be returned; the
  strings \code{false}, \code{no}, and \code{off} generate
  \code{False}.  All other strings cause \exception{ValueError} to be
  raised.
\end{methoddesc}

\begin{methoddesc}[Configuration]{getfloat}{key\optional{,
        default\optional{, min\optional{, max}}}}
  Return the value for \var{key} as a float.  If there is no
  value for \var{key}, returns \var{default}.  If the value cannot
  be converted to a float, \exception{ValueError} is raised.  If
  \var{min} is given and the value is less than \var{min}, or if
  \var{max} is given and the value is greater than \var{max},
  \exception{ValueError} is raised.  No range checking is performed if
  neither \var{min} nor \var{max} is given.
\end{methoddesc}

\begin{methoddesc}[Configuration]{getint}{key\optional{,
        default\optional{, min\optional{, max}}}}
  Return the value for \var{key} as an integer.  If there is no
  value for \var{key}, returns \var{default}.  If the value cannot
  be converted to an integer, \exception{ValueError} is raised.  If
  \var{min} is given and the value is less than \var{min}, or if
  \var{max} is given and the value is greater than \var{max},
  \exception{ValueError} is raised.  No range checking is performed if
  neither \var{min} nor \var{max} is given.
\end{methoddesc}

\begin{methoddesc}[Configuration]{getlist}{key\optional{, default}}
  Return the value for \var{key}, converted to a list.  List items are
  separated by whitespace.
\end{methoddesc}

\begin{methoddesc}[Configuration]{has_key}{key}
  Return \constant{True} if \var{key} has an associated value, otherwise
  returns \constant{False}.
\end{methoddesc}

\begin{methoddesc}[Configuration]{items}{}
  Return a list of key-value pairs from this section, including any
  available from the delegate section.
\end{methoddesc}

\begin{methoddesc}[Configuration]{keys}{}
  Return a list of keys from this section, including any available
  from the delegate section.
\end{methoddesc}

\begin{memberdesc}[Configuration]{name}
  The name of this section, or \code{None}.
\end{memberdesc}

\begin{memberdesc}[Configuration]{type}
  The type of this section as a string.
\end{memberdesc}

\begin{memberdesc}[Configuration]{url}
  The URL of the source this section was loaded from.
\end{memberdesc}


The following method is used to modify the values defined in a
section:

\begin{methoddesc}[Configuration]{addValue}{key, value}
  Add the key \var{key} with the value \var{value}.  If there is
  already a value for \var{key}, \exception{ConfigurationError} is
  raised.
\end{methoddesc}


The following methods are used in retrieving and managing sections:

\begin{methoddesc}[Configuration]{addChildSection}{section}
  Add a section that is a child of the current section.
\end{methoddesc}

\begin{methoddesc}[Configuration]{addNamedSection}{section}
  Add a named section to this section's context.  This is only used to
  add sections that are descendants but not children of the current
  section.
\end{methoddesc}

\begin{methoddesc}[Configuration]{getChildSections}{\optional{type}}
  Returns a sequence of all child sections, in the order in which they
  were added.  If \var{type} is omitted or \code{None}, all sections
  are returned; otherwise only sections of the specified type are
  included.  The delegate is never consulted by this method.
\end{methoddesc}

\begin{methoddesc}[Configuration]{getSection}{type\optional{, name}}
  Returns a single typed section.  The type of the retrieved section
  is given by \var{type}.  If \var{name} is given and not \code{None},
  the name of the section must match \var{name}.  If there is no
  section matching in both name and type,
  \exception{ConfigurationMissingSectionError} is
  raised.  If \var{name} is not given or is \code{None}, there must be
  exactly one child section of type \var{type}; that section is
  returned.  If there is more than one section of type \var{type},
  \exception{ConfigurationConflictingSectionError} is raised.  If
  there is no matching section and a delegate is available, it's
  \method{getSection()} method is called to provide the return value,
  otherwise \code{None} is returned.
\end{methoddesc}

Delegation is supported by one additional method:

\begin{methoddesc}[Configuration]{setDelegate}{section}
  Set the delegate section to \var{section} if not already set.  If
  already set, raises \exception{ConfigurationError}.
\end{methoddesc}

This method is called on each section when the configuration is
completely loaded.  This is called for all sections contained within a
section before it is called on the containing section.

\begin{methoddesc}[Configuration]{finish}{}
  Perform any initialization for the section object that needs to
  occur after the content of the section is loaded and delegation
  chains have been established.  (This method may not have been called
  for delegates before being called on the delegating section.)  The
  default implementation does nothing.
\end{methoddesc}