zconfig.tex

\documentclass{howto}

\title{ZConfig Package Reference}

%\date{\today}
%\release{0.00}

\author{Zope Corporation}
\authoraddress{
    Lafayette Technology Center\\
    513 Prince Edward Street\\
    Fredericksburg, VA 22401\\
    \url{http://www.zope.com/}
}

\begin{document}
\maketitle

\begin{abstract}
\noindent
This document describes the syntax and API used in configuration files
for components of a Zope installation written by Zope Corporation.
\end{abstract}

\tableofcontents


\section{Introduction \label{intro}}

Zope uses a common syntax and API for configuration files designed for
software components written by Zope Corporation.  Third-party software
which is also part of a Zope installation may use a different syntax,
though any software is welcome to use the syntax used by Zope
Corporation.  Any software written in Python is free to use the
\module{ZConfig} software to load such configuration files in order to
ensure compatibility.  This software is covered by the Zope Public
License, version 2.0.

The \module{ZConfig} package has been tested with Python 2.1 and 2.2.
Python 2.0 is not supported.
It only relies on the Python standard library.


\section{Configuration Syntax \label{syntax}}

Like the \ulink{\module{ConfigParser}}
{http://www.python.org/doc/current/lib/module-ConfigParser.html}
format, this format supports key-value pairs arranged in sections.
Unlike the \module{ConfigParser} format, sections are typed and can be
organized hierarchically, and support delegation of value lookup to
other sections.  Additional files may be imported or included at the
top level if needed.  Though both formats are substantially
line-oriented, this format is more flexible.

The intent of supporting nested section is to allow setting up the
configurations for loosely-associated components in a container.  For
example, each process running on a host might get its configuration
section from that host's section of a shared configuration file.  Each
section may use the delegation syntax to share a base configuration
with other components of the same type.

The top level of a configuration file consists of a series of imports,
inclusions, key-value pairs, and sections.

Comments can be added on lines by themselves.  A comment has a
\character{\#} as the first non-space character and extends to the end
of the line:

\begin{verbatim}
# This is a comment
\end{verbatim}

An import is expressed like this:

\begin{verbatim}
%import defaults.conf
\end{verbatim}

while an inclusion is expressed like this:

\begin{verbatim}
%include defaults.conf
\end{verbatim}

The resource to be imported or included can be a relative or absolute
URL, resolved relative to the URL of the resource the import is
located in.


A key-value pair is expressed like this:

\begin{verbatim}
key value
\end{verbatim}

The key may include any non-white characters except for parentheses.
The value contains all the characters between the key and the end of
the line, with surrounding whitespace removed.

Since comments must be on lines by themselves, the \character{\#}
character can be part of a value:

\begin{verbatim}
key value # still part of the value
\end{verbatim}

Sections may be either empty or non-empty.  An empty section may be
used to provide an alias for another section.

A non-empty section starts with a header, contains configuration
data on subsequent lines, and ends with a terminator.

The header for a non-empty section has this form (square brackets
denote optional parts):

\begin{alltt}
<\var{section-type} \optional{\var{name}} \optional{(\var{basename})} >
\end{alltt}

\var{section-type}, \var{name}, and \var{basename} all have the same
syntactic constraints as key names.

The terminator looks like this:

\begin{alltt}
</\var{section-type}>
\end{alltt}

The configuration data in a non-empty section consists of a sequence
of one or more key-value pairs and sections.  For example:

\begin{verbatim}
<my-section>
    key-1 value-1
    key-2 value-2

    <another-section>
        key-3 value-3
    </another-section>
</my-section>
\end{verbatim}

(The indentation is used here for clarity, but is not required for
syntactic correctness.)

If the \var{basename} component is given for a section header
(regardless of the presence of the name component), that section
acquires additional values from another section having \var{basename}
as its \var{name} and an application-supported type.  For example, an
application that supports the types \code{host} and \code{hostclass}
might use configuration like this:

\begin{verbatim}
<hostclass secondary>
    server-type secondary
    port 1234
</hostclass>

<host grendel (secondary)>
    port 2345
</host>
\end{verbatim}

In this application, sections of type \code{host} would be allowed to
acquire configuration data only from the \code{hostclass} type, so the
section named \code{grendel} would only be allowed to to acquire
configuration data from a section with type \code{hostclass} and name
\code{secondary}.  The \code{hostclass} section named \code{secondary}
could in turn acquire additional key-value pairs from some other
section, based on the allowed type relationships of the
\code{hostclass} type.

The header for empty sections is similar to that of non-empty
sections:

\begin{alltt}
<\var{section-type} \optional{\var{name}} \optional{(\var{basename})} />
\end{alltt}


\subsection{Textual Substitution in Values}

\module{ZConfig} provides a limited way to re-use portions of a value
using simple string substitution.  To use this facility, define named
bits of replacement text using the \keyword{\%define} directive, and
reference these texts from values.

The syntax for \keyword{\%define} is:

\begin{alltt}
%define \var{name} \optional{\var{value}}
\end{alltt}

The value of \var{name} must be a sequence of letters, digits, and
underscores, and may not start with a digit; the namespace for these
names is separate from the other namespaces used with
\module{ZConfig}, and is case-insensitive.  If \var{value} is
omitted, it will be the empty string.  If given, there must be
whitespace between \var{name} and \var{value}; \var{value} will not
include any whitespace on either side, just like values from key-value
pairs.

Names must be defined before they are used, and may not be
re-defined.  All names are associated with the source text in which
they are defined, so distinct sources which are referenced using
\keyword{\%import} or \keyword{\%include} are not affected by
definitions created by the resource being parsed.

References to defined names from configuration values use the syntax
described for the \refmodule{ZConfig.Substitution} module.
Configuration values which include a \character{\$} as part of the
actual value will need to use \code{\$\$} to get a single
\character{\$} in the result.

The values of defined names are not processed in any way, and may not
contain references to named definitions.

For example, the value for the \code{key} will evaluate to
\code{value}:

\begin{verbatim}
%define name value
key $name
\end{verbatim} %$ <-- bow to font-lock


\section{\module{ZConfig} --- Basic configuration support}

\declaremodule{}{ZConfig}
\modulesynopsis{Configuration package}

The main \module{ZConfig} package exports two convenience functions:

\begin{funcdesc}{load}{url}
  Load and return a configuration from a URL or pathname given by
  \var{url}.  \var{url} may be a URL, absolute pathname, or relative
  pathname.  Fragment identifiers are not supported.
\end{funcdesc}

\begin{funcdesc}{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{funcdesc}


\section{\module{ZConfig.Context} --- Application context}

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

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 not need to worry
about the application context at all; the \function{load()} function
in the \module{ZConfig} module uses the default context implementation
to glue everything together.

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}{load}{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 overridable by
subclasses; this should suffice for most context specialization.

\begin{methoddesc}{createImportedSection}{parent, url}
  Create a new section that represents a section loaded using
  \keyword{\%import}.  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{parent} is the section that
  contains the \keyword{\%import} statement, and \var{url} is the
  resource that will be loaded into the new section.  This method
  should not cause the \method{addImport()} of \var{parent} to be
  called, nor should it cause the resource to actually be loaded.
  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}{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{load()} 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} using the \function{Parse()} function provided
  by the \refmodule{ZConfig.ApacheStyle} module.  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{\%import} and
\keyword{\%include} statements, if those are defined for the syntax
implemented by the alternate parser.

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

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

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


\section{\module{ZConfig.Config} --- Section objects}

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


The \module{ZConfig.Config} module provides implementations of the
standard key-value section.  There are two implementations: the basic
implementation used for ``internal'' sections, and a subclass that
provides additional support for the \keyword{\%import} statement (used
for the top level of a configuration and for imported resources).

\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}

\begin{classdesc}{ImportingConfiguration}{type, name, url}
  A subclass of \class{Configuration} which supports the context
  needed to support the \keyword{\%import} directive.  This class
  differs from the base class in that it offers an additional method
  and changes the lookup semantics of the \method{get()} method.
\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 \code{True} if \var{key} has an associated value, otherwise
  returns \code{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 descendents 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}

The \class{ImportingConfiguration} subclass offers an additional
method, normally not needed by applications, but possibly useful for
alternate configuration parsers.  Objects returned by the
context object's \method{createToplevelSection()} method need to
support this interface.

\begin{methoddesc}[ImportingConfiguration]{addImport}{section}
  Add a configuration generated from an import.
\end{methoddesc}


\section{\module{ZConfig.Common} --- Exceptions}

\declaremodule{}{ZConfig.Common}
\modulesynopsis{Exceptions}

\begin{excdesc}{ConfigurationError}
  Base class for exceptions specific to the \module{ZConfig} package.
  All instances provide a \member{message} attribute that describes
  the specific error.
\end{excdesc}

\begin{excdesc}{ConfigurationSyntaxError}
  Exception raised when a configuration source does not conform to the
  allowed syntax.  In addition to the \member{message} attribute,
  exceptions of this type offer the \member{url} and \member{lineno}
  attributes, which provide the URL and line number at which the error
  was detected.
\end{excdesc}

\begin{excdesc}{ConfigurationTypeError}
\end{excdesc}

\begin{excdesc}{ConfigurationMissingSectionError}
  Raised when a requested named section is not available.
\end{excdesc}

\begin{excdesc}{ConfigurationConflictingSectionError}
  Raised when a request for a section cannot be fulfilled without
  ambiguity.
\end{excdesc}


\section{\module{ZConfig.ApacheStyle} --- Apache-style parser}

\declaremodule{}{ZConfig.ApacheStyle}
\modulesynopsis{Parser for Apache-style configurations}

The \module{ZConfig.ApacheStyle} module implements the configuration
parser.  Most applications will not need to use this module directly.

This module provides a single function:

\begin{funcdesc}{Parse}{resource, context, section}
  Parse text from the resource represented by \var{resource}; this is
  an object that conforms to the same interface as the \var{resource}
  parameter of the \class{Context} object's \method{parse()} method.
  The application context is given as \var{context}, and the section
  object that values and sections should be added to is given as
  \var{section}.
\end{funcdesc}


\section{\module{ZConfig.Substitution} --- String substitution}

\declaremodule{}{ZConfig.Substitution}
\modulesynopsis{Shell-style string substitution helper}

This module provides a basic substitution facility similar to that
found in the Bourne shell (\program{sh} on most \UNIX{} platforms).  

The replacements supported by this module include:

\begin{tableiii}{l|l|c}{code}{Source}{Replacement}{Notes}
  \lineiii{\$\$}{\code{\$}}{(1)}
  \lineiii{\$\var{name}}{The result of looking up \var{name}}{(2)}
  \lineiii{\$\{\var{name}\}}{The result of looking up \var{name}}{}
\end{tableiii}

\noindent
Notes:
\begin{description}
  \item[(1)]  This is different from the Bourne shell, which uses
              \code{\textbackslash\$} to generate a \character{\$} in
              the result text.  This difference avoids having as many
              special characters in the syntax.

  \item[(2)]  Any character which immediately follows \var{name} may
              not be a valid character in a name.
\end{description}

In each case, \var{name} is a non-empty sequence of alphanumeric and
underscore characters not starting with a digit.  If there is not a
replacement for \var{name}, an empty string is used.
Note that the lookup is expected to be case-insensitive; this module
will always use a lower-case version of the name to perform the query.

This module provides these functions:

\begin{funcdesc}{substitute}{s, mapping}
  Substitute values from \var{mapping} into \var{s}.  \var{mapping}
  can be a \class{dict} or any type that supports the \method{get()}
  method of the mapping protocol.  Replacement
  values are copied into the result without further interpretation.
  Raises \exception{SubstitutionSyntaxError} if there are malformed
  constructs in \var{s}.
\end{funcdesc}

\begin{funcdesc}{isname}{s}
  Returns \code{True} if \var{s} is a valid name for a substitution
  text, otherwise returns \code{False}.
\end{funcdesc}

The following exception is defined:

\begin{excdesc}{SubstitutionSyntaxError}
  Raised when the source text contains syntactical errors.  Instances
  provide the attribute \member{message}, which contains a description
  of the error.
\end{excdesc}


\subsection{Examples}

\begin{verbatim}
>>> from ZConfig.Substitution import substitute
>>> d = {'name': 'value',
...      'top': '$middle',
...      'middle' : 'bottom'}
>>>
>>> substitute('$name', d)
'value'
>>> substitute('$top', d)
'$middle'
\end{verbatim}


\end{document}