Skip to content

Z
ZEO
Commit 0ab5ef46 authored by Fred Drake's avatar Fred Drake
Browse files
Options

- documented the "prefix" stuff 

- fixed datatype of the values for "handler" attributes
- removed/commented out all mentions of schema component extension;
  that's really not complete and should probably be thought through
  again
- moved docs for legacy API out; these should not be generally
  documented
- misc. small fixes
parent bea5cc5f
Show whitespace changes
Inline Side-by-side
Showing with 70 additions and 327 deletions
doc/ZConfig/zconfig.tex
View file @ 0ab5ef46
......@@ -257,8 +257,6 @@ key $name
\section{Writing Configuration Schema \label{writing-schema}}
XXX to be written
\module{ZConfig} schema are written as XML documents.
Data types are searched in a special namespace defined by the data
......@@ -287,7 +285,9 @@ The following elements are used to describe a schema:
\begin{attributedesc}{datatype}{\datatype{basic-key}
or \datatype{dotted-name}}
The data type converter which will be applied to the value of this
section.
section. If the value is a \datatype{dotted-name} that begins
with a period, the value of \attribute{prefix} will be pre-pended,
if set.
\end{attributedesc}
\begin{attributedesc}{handler}{\datatype{basic-key}}
......@@ -298,10 +298,17 @@ The following elements are used to describe a schema:
this section. This can be used to constrain key values in
different ways; two data types which may be especially useful are
the \datatype{identifier} and \datatype{ipaddr-or-hostname}
types. The default value is \datatype{basic-key}.
types. If the value is a \datatype{dotted-name} that begins
with a period, the value of \attribute{prefix} will be pre-pended,
if set. The default value is \datatype{basic-key}.
\end{attributedesc}
\begin{attributedesc}{prefix}{\datatype{dotted-name}}
Prefix to be pre-pended in front of partial dotted-names that
start with a period. The value of this attribute is used in all
contexts with the \element{schema} element if it hasn't been
overridden by an inner element with a \attribute{prefix}
attribute.
\end{attributedesc}
\end{elementdesc}
......@@ -348,7 +355,9 @@ The following elements are used to describe a schema:
\begin{attributedesc}{datatype}{\datatype{basic-key}
or \datatype{dotted-name}}
The data type converter which will be applied to the value of this
section.
section. If the value is a \datatype{dotted-name} that begins
with a period, the value of \attribute{prefix} will be pre-pended,
if set.
\end{attributedesc}
\begin{attributedesc}{extends}{\datatype{basic-key}}
......@@ -372,7 +381,9 @@ The following elements are used to describe a schema:
this section. This can be used to constrain key values in
different ways; two data types which may be especially useful are
the \datatype{identifier} and \datatype{ipaddr-or-hostname}
types. The default value is \datatype{basic-key}.
types. If the value is a \datatype{dotted-name} that begins
with a period, the value of \attribute{prefix} will be pre-pended,
if set. The default value is \datatype{basic-key}.
\end{attributedesc}
\begin{attributedesc}{name}{\datatype{basic-key}}
......@@ -380,6 +391,10 @@ The following elements are used to describe a schema:
\end{attributedesc}
\begin{attributedesc}{prefix}{\datatype{dotted-name}}
Prefix to be pre-pended in front of partial dotted-names that
start with a period. The value of this attribute is used in all
contexts in the \element{sectiontype} element. If omitted, the
prefix specified by a containing context is used if specified.
\end{attributedesc}
\end{elementdesc}
......@@ -419,7 +434,9 @@ The following elements are used to describe a schema:
\begin{attributedesc}{datatype}{\datatype{basic-key}
or \datatype{dotted-name}}
The data type converter which will be applied to the value of this
key.
key. If the value is a \datatype{dotted-name} that begins
with a period, the value of \attribute{prefix} will be pre-pended,
if set.
\end{attributedesc}
\begin{attributedesc}{default}{\datatype{string}}
......@@ -430,7 +447,7 @@ The following elements are used to describe a schema:
\attribute{required} attribute is \code{yes}.
\end{attributedesc}
\begin{attributedesc}{handler}{\datatype{dotted-name}}
\begin{attributedesc}{handler}{\datatype{basic-key}}
\end{attributedesc}
\begin{attributedesc}{name}{\datatype{basic-key}}
......@@ -472,15 +489,17 @@ The following elements are used to describe a schema:
\begin{attributedesc}{datatype}{\datatype{basic-key}
or \datatype{dotted-name}}
The data type converter which will be applied to the value of this
key.
key. If the value is a \datatype{dotted-name} that begins
with a period, the value of \attribute{prefix} will be pre-pended,
if set.
\end{attributedesc}
\begin{attributedesc}{handler}{\datatype{dotted-name}}
\begin{attributedesc}{handler}{\datatype{basic-key}}
\end{attributedesc}
\begin{attributedesc}{name}{\datatype{basic-key}}
The name of the key, as it must be given in a configuration
instance, or `\code{*}'. If the value is `\code{*}', any name not
instance, or `\code{+}'. If the value is `\code{+}', any name not
already specified as a key may be used, and the configuration
value for the key will be a dictionary mapping from the key name
to the value. In this case, the \attribute{attribute} attribute
......@@ -518,7 +537,7 @@ The following elements are used to describe a schema:
or \code{+}.
\end{attributedesc}
\begin{attributedesc}{handler}{\datatype{dotted-name}}
\begin{attributedesc}{handler}{\datatype{basic-key}}
\end{attributedesc}
\begin{attributedesc}{name}{\datatype{basic-key}}
......@@ -563,7 +582,7 @@ The following elements are used to describe a schema:
of matching sections.
\end{attributedesc}
\begin{attributedesc}{handler}{\datatype{dotted-name}}
\begin{attributedesc}{handler}{\datatype{basic-key}}
\end{attributedesc}
\begin{attributedesc}{name}{\datatype{basic-key}}
......@@ -600,11 +619,10 @@ The following elements are used to describe a schema:
XXX need more explanation
\module{ZConfig} supports extensible schema components that can be
\module{ZConfig} supports schema components that can be
provided by disparate components, and allows them to be knit together
into concrete schema for applications. Neither components nor
extensions can add additional keys or sections in the application
schema.
into concrete schema for applications. Components cannot add
additional keys or sections in the application schema.
A schema \dfn{component} is allowed to define new abstract and
section types. It is not allowed to extend application types or
......@@ -612,41 +630,54 @@ include additional types in application-provided abstract types.
Components are identified using a dotted-name, similar to a Python
module name. For example, one component may be \code{zodb.storage}.
A schema component \dfn{extension} is allowed to define new abstract
and section types, extend types provided by the component it extends,
and include new section types in abstract types provided by the
component. The expected usage is that extensions will provide one or
more concrete types that implement abstract types defined by the
component.
%A schema component \dfn{extension} is allowed to define new abstract
%and section types, extend types provided by the component it extends,
%and include new section types in abstract types provided by the
%component. The expected usage is that extensions will provide one or
%more concrete types that implement abstract types defined by the
%component.
A library of schema components is stored as a directory tree, where
each component is located in a directory within the tree. That
directory must contain a file named \file{component.xml} which defines
the types provided by that component; it must have a
\element{component} element as the document element. Extensions to a
component are stored in immediate subdirectories; a file
\file{extension.xml} provides the extension types. Extensions must
have an \element{extension} element as the document element.
Schema components are stored alongside application code since they
directly reference datatype code. Schema components are provided by
Python packages; packages which contain a file named
\file{component.xml} can be ``imported''. The \file{component.xml}
file defines the types provided by that component; it must have a
\element{component} element as the document element.
%Extensions to a component are stored in immediate subdirectories; a
%file \file{extension.xml} provides the extension types. Extensions
%must have an \element{extension} element as the document element.
\subsection{Schema Component Elements \label{component-elements}}
The following elements are used as the document elements of schema
components and schema component extensions.
The following element is used as the document element for schema
components. Note that schema components do not allow keys and
sections to be added to the top-level of a schema; they serve only to
provide type definitions.
\begin{elementdesc}{component}{description?, (abstracttype | sectiontype)*}
The top-level element for schema components.
\begin{attributedesc}{prefix}{\datatype{dotted-name}}
Prefix to be pre-pended in front of partial dotted-names that
start with a period. The value of this attribute is used in all
contexts within the \element{component} element if it hasn't been
overridden by an inner element with a \attribute{prefix}
attribute.
\end{attributedesc}
\end{elementdesc}
\begin{elementdesc}{extensions}{description?, (abstracttype | sectiontype)*}
The top-level element for schema component extensions.
%\begin{elementdesc}{extension}{description?, (abstracttype | sectiontype)*}
% The top-level element for schema component extensions.
\begin{attributedesc}{prefix}{\datatype{dotted-name}}
\end{attributedesc}
\end{elementdesc}
% \begin{attributedesc}{prefix}{\datatype{dotted-name}}
% Prefix to be pre-pended in front of partial dotted-names that
% start with a period. The value of this attribute is used in all
% contexts within the \element{extension} element if it hasn't been
% overridden by an inner element with a \attribute{prefix}
% attribute.
% \end{attributedesc}
%\end{elementdesc}
\section{Standard \module{ZConfig} Datatypes\label{standard-datatypes}}
......@@ -1260,294 +1291,6 @@ schema:
\verbatiminput{schema.dtd}
% 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 (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}
%\input{oldapi}
\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