[Zope-Checkins] CVS: Zope/lib/python/ZConfig/doc - zconfig.tex:1.11.4.1
Andreas Jung
andreas@andreas-jung.com
Sat, 9 Nov 2002 03:43:29 -0500
Update of /cvs-repository/Zope/lib/python/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv26094/lib/python/ZConfig/doc
Modified Files:
Tag: ajung-restructuredtext-integration-branch
zconfig.tex
Log Message:
merge from trunk
=== Zope/lib/python/ZConfig/doc/zconfig.tex 1.11 => 1.11.4.1 ===
--- Zope/lib/python/ZConfig/doc/zconfig.tex:1.11 Mon Oct 21 14:59:54 2002
+++ Zope/lib/python/ZConfig/doc/zconfig.tex Sat Nov 9 03:42:58 2002
@@ -183,7 +183,7 @@
\declaremodule{}{ZConfig}
\modulesynopsis{Configuration package}
-The main \module{ZConfig} package exports a single function:
+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
@@ -191,6 +191,14 @@
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}
@@ -218,8 +226,9 @@
replacement of the class.
\end{classdesc}
-The context object offers one method that is intended to be called
-once:
+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
@@ -227,6 +236,14 @@
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.
@@ -448,6 +465,17 @@
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
@@ -507,10 +535,10 @@
\end{funcdesc}
-\section{\module{ZConfig.Interpolation} --- String interpolation}
+\section{\module{ZConfig.Substitution} --- String substitution}
-\declaremodule{}{ZConfig.Interpolation}
-\modulesynopsis{Shell-style string interpolation helper}
+\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).
@@ -536,47 +564,53 @@
\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}, it is replaced with an empty string.
+underscore characters not starting with a digit. If there is not a
+replacement for \var{name}, these functions search up the containment
+chain for a suitable replacement. The containment chain is found by
+looking for an attribute \member{container} on the \var{mapping}
+object; the value of that attribute should be another mapping or
+\code{None}. If this search does not yield a value, an empty string
+is used.
For these functions, the \var{mapping} argument can be a \class{dict},
or any type that supports the \method{get()} method of the mapping
-protocol.
+protocol. The \member{container} attribute used to search the
+containment chain is optional.
-\begin{funcdesc}{interpolate}{s, mapping}
- Interpolate values from \var{mapping} into \var{s}. Replacement
+\begin{funcdesc}{substitute}{s, mapping}
+ Substitute values from \var{mapping} into \var{s}. Replacement
values are copied into the result without further interpretation.
- Raises \exception{InterpolationSyntaxError} if there are malformed
+ Raises \exception{SubstitutionSyntaxError} if there are malformed
constructs in \var{s}.
\end{funcdesc}
\begin{funcdesc}{get}{mapping, name\optional{, default}}
- Return the value for \var{name} from \var{mapping}, interpolating
+ Return the value for \var{name} from \var{mapping}, replacing
values recursively if needed. If \var{name} cannot be found in
\var{mapping}, \var{default} is returned without being
- interpolated.
- Raises \exception{InterpolationSyntaxError} if there are malformed
- constructs in \var{s}, or \exception{InterpolationRecursionError} if
+ replaced.
+ Raises \exception{SubstitutionSyntaxError} if there are malformed
+ constructs in \var{s}, or \exception{SubstitutionRecursionError} if
any name expands to include a reference to itself either directly or
indirectly.
\end{funcdesc}
The following exceptions are defined:
-\begin{excdesc}{InterpolationError}
- Base class for errors raised by the \module{ZConfig.Interpolation}
+\begin{excdesc}{SubstitutionError}
+ Base class for errors raised by the \module{ZConfig.Substitution}
module. Instances provide the attributes \member{message} and
\member{context}. \member{message} contains a description of the
error. \member{context} is either \code{None} or a list of names
- that have been looked up in the case of nested interpolation.
+ that have been looked up in the case of nested substitution.
\end{excdesc}
-\begin{excdesc}{InterpolationSyntaxError}
- Raised when interpolation source text contains syntactical errors.
+\begin{excdesc}{SubstitutionSyntaxError}
+ Raised when the source text contains syntactical errors.
\end{excdesc}
-\begin{excdesc}{InterpolationRecursionError}
- Raised when a nested interpolation is recursive. The
+\begin{excdesc}{SubstitutionRecursionError}
+ Raised when a nested substitution is recursive. The
\member{context} attribute will always be a list for this
exception. An additional attribute, \member{name}, gives the name
for which an recursive reference was detected.
@@ -585,18 +619,18 @@
\subsection{Examples}
-These examples show how \function{get()} and \function{interpolate()}
+These examples show how \function{get()} and \function{substitute()}
differ.
\begin{verbatim}
->>> from ZConfig.Interpolation import get, interpolate
+>>> from ZConfig.Substitution import get, substitute
>>> d = {'name': 'value',
... 'top': '$middle',
... 'middle' : 'bottom'}
>>>
->>> interpolate('$name', d)
+>>> substitute('$name', d)
'value'
->>> interpolate('$top', d)
+>>> substitute('$top', d)
'$middle'
>>>
>>> get(d, 'name')