New location for documentation of legacy API.

doc/ZConfig/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}