Skip to content

Z
ZODB
Commit c1770d0d authored by Fred Drake's avatar Fred Drake
Browse files
Options

- comment out material discussing section "delegation" since it's not 

  supported in the current version when using schema
- move the docs for the backward-compatibility modules to the end,
  nicely out of the way
parent edc33afc
Hide whitespace changes
Inline Side-by-side
Showing with 292 additions and 287 deletions
doc/ZConfig/zconfig.tex
View file @ c1770d0d
......@@ -66,17 +66,17 @@ 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 included if needed. Though
both formats are substantially line-oriented, this format is more
flexible.
organized hierarchically.
% XXX and support delegation of value lookup to other sections.
Additional files may be included 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.
section from that host's section of a shared configuration file.
% XXX 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
inclusions, key-value pairs, and sections.
......@@ -127,11 +127,12 @@ 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})} >
<\var{section-type} \optional{\var{name}} >
\end{alltt}
% <\var{section-type} \optional{\var{name}} \optional{(\var{basename})} >
\var{section-type}, \var{name}, and \var{basename} all have the same
syntactic constraints as key names.
\var{section-type} and \var{name} % and \var{basename}
all have the same syntactic constraints as key names.
The terminator looks like this:
......@@ -156,39 +157,40 @@ of one or more key-value pairs and sections. For example:
(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.
% 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:
sections, but there is no terminator:
\begin{alltt}
<\var{section-type} \optional{\var{name}} \optional{(\var{basename})} />
<\var{section-type} \optional{\var{name}} />
\end{alltt}
% <\var{section-type} \optional{\var{name}} \optional{(\var{basename})} />
\subsection{Textual Substitution in Values}
......@@ -580,6 +582,258 @@ attributes:
\end{tableii}
\section{\module{ZConfig.datatypes} --- Default data type registry}
\declaremodule{}{ZConfig.datatypes}
\modulesynopsis{Default implementation of a data type registry}
The \module{ZConfig.datatypes} module provides the implementation of
the default data type registry and all the standard data types
supported by \module{ZConfig}. A number of convenience classes are
also provided to assist in the creation of additional datatypes.
A \dfn{datatype registry} is an object that provides conversion
functions for data types. The interface for a registry is fairly
simple.
A \dfn{conversion function} is any callable object that accepts a
single argument and returns a suitable value, or raises an exception
if the input value is not acceptable. \exception{ValueError} is the
preferred exception for disallowed inputs, but any other exception
will be properly propogated.
\begin{classdesc}{Registry}{\optional{stock}}
Implementation of a simple type registry. If given, \var{stock}
should be a mapping which defines the ``built-in'' data types for
the registry; if omitted or \code{None}, the standard set of data
types is used (see section~\ref{standard-datatypes}, ``Standard
\module{ZConfig} Datatypes'').
\end{classdesc}
\class{Registry} objects have the following methods:
\begin{methoddesc}{get}{name}
Return the type conversion routine for \var{name}. If the
conversion function cannot be found, an (unspecified) exception is
raised. If the name is not provided in the stock set of data types
by this registry and has not otherwise been registered, this method
uses the \method{search()} method to load the conversion function.
This is the only method the rest of \module{ZConfig} requires.
\end{methoddesc}
\begin{methoddesc}{register}{name, conversion}
Registery the data type name \var{name} to use the conversion
function \var{conversion}. If \var{name} is already registered or
provided as a stock data type, \exception{ValueError} is raised
(this includes the case when \var{name} was found using the
\method{search()} method).
\end{methoddesc}
\begin{methoddesc}{search}{name}
This is a helper method for the default implementation of the
\method{get()} method. If \var{name} is a Python dotted-name, this
method loads the value for the name by dynamically importing the
containing module and extracting the value of the name. The name
must refer to a usable conversion function.
\end{methoddesc}
The following classes are provided to define conversion functions:
\begin{classdesc}{MemoizedConversion}{conversion}
Simple memoization for potentially expensive conversions. This
conversion helper caches each successful conversion for re-use at a
later time; failed conversions are not cached in any way, since it
is difficult to raise a meaningful excpetion providing information
about the specific failure.
\end{classdesc}
\begin{classdesc}{RangeCheckedConversion}{conversion\optional{,
min\optional{, max}}}
Helper that performs range checks on the result of another
conversion. Values passed to instances of this conversion are
converted using \var{conversion} and then range checked. \var{min}
and \var{max}, if given and not \code{None}, are the inclusive
endpoints of the allowed range. Values returned by \var{conversion}
which lay outside the range described by \var{min} and \var{max}
cause \exception{ValueError} to be raised.
\end{classdesc}
\begin{classdesc}{RegularExpressionConversion}{regex}
Conversion that checks that the input matches the regular expression
\var{regex}. If it matches, returns the input, otherwise raises
\exception{ValueError}.
\end{classdesc}
\section{\module{ZConfig.loader} --- Resource loading support}
\declaremodule{}{ZConfig.loader}
\modulesynopsis{Support classes for resource loading}
This module provides some helper classes used by the primary APIs
exported by the \module{ZConfig} package. These classes may be useful
for some applications, especially applications that want to use a
non-default data type registry.
\begin{classdesc}{Resource}{file, url\optional{, fragment}}
Object that allows an open file object and a URL to be bound
together to ease handling. Instances have the attributes
\member{file}, \member{url}, and \member{fragment} which store the
constructor arguments. These objects also have a \method{close()}
method which will call \method{close()} on \var{file}, then set the
\member{file} attribute to \code{None} and the \member{closed} to
\code{True}.
\end{classdesc}
\begin{classdesc}{BaseLoader}{}
Base class for loader objects. This should not be instantiated
directly, as the \method{loadResource()} method must be overridden
for the instance to be used via the public API.
\end{classdesc}
\begin{classdesc}{ConfigLoader}{schema}
Loader for configuration files. Each configuration file must
conform to the schema \var{schema}. The \method{load*()} methods
return a tuple consisting of the configuration object and a
composite handler.
\end{classdesc}
\begin{classdesc}{SchemaLoader}{\optional{registry}}
Loader that loads schema instances. All schema loaded by a
\class{SchemaLoader} will use the same data type registry. If
\var{registry} is provided and not \code{None}, it will be used,
otherwise an instance of \class{ZConfig.datatypes.Registry} will be
used.
\end{classdesc}
\subsection{Loader Objects}
Loader objects provide a general public interface, an inteface which
subclasses must implement, and some utility methods.
The following methods provide the public interface:
\begin{methoddesc}[loader]{loadURL}{url}
Open and load a resource specified by the URL \var{url}.
This method uses the \method{loadResource()} method to perform the
actual load, and returns whatever that method returns.
\end{methoddesc}
\begin{methoddesc}[loader]{loadFile}{file\optional{, url}}
Load from an open file object, \var{file}. If given and not
\code{None}, \var{url} should be the URL of the resource represented
by \var{file}. If omitted or \code{None}, the \member{name}
attribute of \var{file} is used to compute a \code{file:} URL, if
present.
This method uses the \method{loadResource()} method to perform the
actual load, and returns whatever that method returns.
\end{methoddesc}
The following method must be overridden by subclasses:
\begin{methoddesc}[loader]{loadResource}{resource}
Subclasses of \class{BaseLoader} must implement this method to
actually load the resource and return the appropriate
application-level object.
\end{methoddesc}
The following methods can be used as utilities:
\begin{methoddesc}[loader]{normalizeURL}{url-or-path}
Return a URL for \var{url-or-path}. If \var{url-or-path} refers to
an existing file, the corresponding \code{file:} URL is returned.
Otherwise \var{url-or-path} is checked for sanity: if it
does not have a schema, \exception{ValueError} is raised, and if it
does have a fragment identifier, \exception{ConfigurationError} is
raised.
\end{methoddesc}
\begin{methoddesc}[loader]{openResource}{url}
Returns a resource object that represents the URL \var{url}. The
URL is opened using the \function{urllib2.urlopen()} function, and
the returned resource object is created using
\method{createResource()}.
\end{methoddesc}
\begin{methoddesc}[loader]{createResource}{file, url}
Returns a resource object for an open file and URL, given as
\var{file} and \var{url}, respectively. This may be overridden by a
subclass if an alternate resource implementation is desired.
\end{methoddesc}
\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}, the exception
\exception{SubstitutionReplacementError} is raised.
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}
\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}
% The modules described here have been left in the package while
% everything is updated to use the schema-based configurations.
\section{\module{ZConfig.Context} --- Application context}
\declaremodule{}{ZConfig.Context}
......@@ -868,253 +1122,4 @@ section before it is called on the containing section.
\end{methoddesc}
\section{\module{ZConfig.datatypes} --- Default data type registry}
\declaremodule{}{ZConfig.datatypes}
\modulesynopsis{Default implementation of a data type registry}
The \module{ZConfig.datatypes} module provides the implementation of
the default data type registry and all the standard data types
supported by \module{ZConfig}. A number of convenience classes are
also provided to assist in the creation of additional datatypes.
A \dfn{datatype registry} is an object that provides conversion
functions for data types. The interface for a registry is fairly
simple.
A \dfn{conversion function} is any callable object that accepts a
single argument and returns a suitable value, or raises an exception
if the input value is not acceptable. \exception{ValueError} is the
preferred exception for disallowed inputs, but any other exception
will be properly propogated.
\begin{classdesc}{Registry}{\optional{stock}}
Implementation of a simple type registry. If given, \var{stock}
should be a mapping which defines the ``built-in'' data types for
the registry; if omitted or \code{None}, the standard set of data
types is used (see section~\ref{standard-datatypes}, ``Standard
\module{ZConfig} Datatypes'').
\end{classdesc}
\class{Registry} objects have the following methods:
\begin{methoddesc}{get}{name}
Return the type conversion routine for \var{name}. If the
conversion function cannot be found, an (unspecified) exception is
raised. If the name is not provided in the stock set of data types
by this registry and has not otherwise been registered, this method
uses the \method{search()} method to load the conversion function.
This is the only method the rest of \module{ZConfig} requires.
\end{methoddesc}
\begin{methoddesc}{register}{name, conversion}
Registery the data type name \var{name} to use the conversion
function \var{conversion}. If \var{name} is already registered or
provided as a stock data type, \exception{ValueError} is raised
(this includes the case when \var{name} was found using the
\method{search()} method).
\end{methoddesc}
\begin{methoddesc}{search}{name}
This is a helper method for the default implementation of the
\method{get()} method. If \var{name} is a Python dotted-name, this
method loads the value for the name by dynamically importing the
containing module and extracting the value of the name. The name
must refer to a usable conversion function.
\end{methoddesc}
The following classes are provided to define conversion functions:
\begin{classdesc}{MemoizedConversion}{conversion}
Simple memoization for potentially expensive conversions. This
conversion helper caches each successful conversion for re-use at a
later time; failed conversions are not cached in any way, since it
is difficult to raise a meaningful excpetion providing information
about the specific failure.
\end{classdesc}
\begin{classdesc}{RangeCheckedConversion}{conversion\optional{,
min\optional{, max}}}
Helper that performs range checks on the result of another
conversion. Values passed to instances of this conversion are
converted using \var{conversion} and then range checked. \var{min}
and \var{max}, if given and not \code{None}, are the inclusive
endpoints of the allowed range. Values returned by \var{conversion}
which lay outside the range described by \var{min} and \var{max}
cause \exception{ValueError} to be raised.
\end{classdesc}
\begin{classdesc}{RegularExpressionConversion}{regex}
Conversion that checks that the input matches the regular expression
\var{regex}. If it matches, returns the input, otherwise raises
\exception{ValueError}.
\end{classdesc}
\section{\module{ZConfig.loader} --- Resource loading support}
\declaremodule{}{ZConfig.loader}
\modulesynopsis{Support classes for resource loading}
This module provides some helper classes used by the primary APIs
exported by the \module{ZConfig} package. These classes may be useful
for some applications, especially applications that want to use a
non-default data type registry.
\begin{classdesc}{Resource}{file, url\optional{, fragment}}
Object that allows an open file object and a URL to be bound
together to ease handling. Instances have the attributes
\member{file}, \member{url}, and \member{fragment} which store the
constructor arguments. These objects also have a \method{close()}
method which will call \method{close()} on \var{file}, then set the
\member{file} attribute to \code{None} and the \member{closed} to
\code{True}.
\end{classdesc}
\begin{classdesc}{BaseLoader}{}
Base class for loader objects. This should not be instantiated
directly, as the \method{loadResource()} method must be overridden
for the instance to be used via the public API.
\end{classdesc}
\begin{classdesc}{ConfigLoader}{schema}
Loader for configuration files. Each configuration file must
conform to the schema \var{schema}. The \method{load*()} methods
return a tuple consisting of the configuration object and a
composite handler.
\end{classdesc}
\begin{classdesc}{SchemaLoader}{\optional{registry}}
Loader that loads schema instances. All schema loaded by a
\class{SchemaLoader} will use the same data type registry. If
\var{registry} is provided and not \code{None}, it will be used,
otherwise an instance of \class{ZConfig.datatypes.Registry} will be
used.
\end{classdesc}
\subsection{Loader Objects}
Loader objects provide a general public interface, an inteface which
subclasses must implement, and some utility methods.
The following methods provide the public interface:
\begin{methoddesc}[loader]{loadURL}{url}
Open and load a resource specified by the URL \var{url}.
This method uses the \method{loadResource()} method to perform the
actual load, and returns whatever that method returns.
\end{methoddesc}
\begin{methoddesc}[loader]{loadFile}{file\optional{, url}}
Load from an open file object, \var{file}. If given and not
\code{None}, \var{url} should be the URL of the resource represented
by \var{file}. If omitted or \code{None}, the \member{name}
attribute of \var{file} is used to compute a \code{file:} URL, if
present.
This method uses the \method{loadResource()} method to perform the
actual load, and returns whatever that method returns.
\end{methoddesc}
The following method must be overridden by subclasses:
\begin{methoddesc}[loader]{loadResource}{resource}
Subclasses of \class{BaseLoader} must implement this method to
actually load the resource and return the appropriate
application-level object.
\end{methoddesc}
The following methods can be used as utilities:
\begin{methoddesc}[loader]{normalizeURL}{url-or-path}
Return a URL for \var{url-or-path}. If \var{url-or-path} refers to
an existing file, the corresponding \code{file:} URL is returned.
Otherwise \var{url-or-path} is checked for sanity: if it
does not have a schema, \exception{ValueError} is raised, and if it
does have a fragment identifier, \exception{ConfigurationError} is
raised.
\end{methoddesc}
\begin{methoddesc}[loader]{openResource}{url}
Returns a resource object that represents the URL \var{url}. The
URL is opened using the \function{urllib2.urlopen()} function, and
the returned resource object is created using
\method{createResource()}.
\end{methoddesc}
\begin{methoddesc}[loader]{createResource}{file, url}
Returns a resource object for an open file and URL, given as
\var{file} and \var{url}, respectively. This may be overridden by a
subclass if an alternate resource implementation is desired.
\end{methoddesc}
\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}, the exception
\exception{SubstitutionReplacementError} is raised.
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}
\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}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7