[Zodb-checkins] CVS: Zope/lib/python/ZConfig/doc -
schema.dtd:1.6.26.4 zconfig.pdf:1.7.26.4
zconfig.tex:1.70.16.4 oldapi.tex:NONE
Fred L. Drake, Jr.
fred at zope.com
Tue Oct 7 15:36:55 EDT 2003
Update of /cvs-repository/Zope/lib/python/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv6557/doc
Modified Files:
Tag: Zope-2_7-branch
schema.dtd zconfig.pdf zconfig.tex
Removed Files:
Tag: Zope-2_7-branch
oldapi.tex
Log Message:
Merge the ZConfig trunk to Zope 2.7.
This adds support for two approaches to schema extension.
=== Zope/lib/python/ZConfig/doc/schema.dtd 1.6.26.3 => 1.6.26.4 ===
--- Zope/lib/python/ZConfig/doc/schema.dtd:1.6.26.3 Fri Sep 19 17:24:50 2003
+++ Zope/lib/python/ZConfig/doc/schema.dtd Tue Oct 7 15:36:22 2003
@@ -83,8 +83,7 @@
attribute NMTOKEN #IMPLIED
type NMTOKEN #REQUIRED
handler NMTOKEN #IMPLIED
- minOccurs NMTOKEN #IMPLIED
- maxOccurs NMTOKEN #IMPLIED>
+ required (yes|no) "no">
<!ELEMENT multisection (description?)>
<!ATTLIST multisection
=== Zope/lib/python/ZConfig/doc/zconfig.pdf 1.7.26.3 => 1.7.26.4 ===
<Binary-ish file>
=== Zope/lib/python/ZConfig/doc/zconfig.tex 1.70.16.3 => 1.70.16.4 ===
--- Zope/lib/python/ZConfig/doc/zconfig.tex:1.70.16.3 Fri Sep 19 17:24:50 2003
+++ Zope/lib/python/ZConfig/doc/zconfig.tex Tue Oct 7 15:36:22 2003
@@ -20,8 +20,8 @@
\title{ZConfig Package Reference}
%\date{\today}
-\release{1.0}
-\setshortversion{1.0}
+\release{2.0}
+\setshortversion{2.0}
\author{Zope Corporation}
\authoraddress{
@@ -56,8 +56,8 @@
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.
+The \module{ZConfig} package has been tested with Python 2.1, 2.2, and
+2.3. Python 2.0 is not supported.
\module{ZConfig} only relies on the Python standard library.
Configurations which use \module{ZConfig} are described using
@@ -78,16 +78,15 @@
format, this format supports key-value pairs arranged in sections.
Unlike the \module{ConfigParser} format, sections are typed and can be
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.
+Additional files may be included if needed. Schema components not
+specified in the application schema can be imported from the
+configuration file. 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.
-% 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.
@@ -140,10 +139,9 @@
\begin{alltt}
<\var{section-type} \optional{\var{name}} >
\end{alltt}
-% <\var{section-type} \optional{\var{name}} \optional{(\var{basename})} >
-\var{section-type} and \var{name} % and \var{basename}
-all have the same syntactic constraints as key names.
+\var{section-type} and \var{name} all have the same syntactic
+constraints as key names.
The terminator looks like this:
@@ -168,40 +166,92 @@
(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 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, but there is no terminator:
\begin{alltt}
<\var{section-type} \optional{\var{name}} />
\end{alltt}
-% <\var{section-type} \optional{\var{name}} \optional{(\var{basename})} />
+
+
+\subsection{Extending the Configuration Schema}
+
+As we'll see in section~\ref{writing-schema}, ``Writing Configuration
+Schema,'' what can be written in a configuration is controlled by
+schemas which can be built from \emph{components}. These components
+can also be used to extend the set of implementations of objects the
+application can handle. What this means when writing a configuration
+is that third-party implementations of application object types can be
+used wherever those application types are used in the configuration,
+if there's a \module{ZConfig} component available for that
+implementation.
+
+The configuration file can use an \keyword{\%import} directive to load
+a named component:
+
+\begin{verbatim}
+%import Products.Ape
+\end{verbatim}
+
+The text to the right of the \keyword{\%import} keyword must be the
+name of a Python package; the \module{ZConfig} component provided by
+that package will be loaded and incorporated into the schema being
+used to load the configuration file. After the import, section types
+defined in the component may be used in the configuration.
+
+More detail is needed for this to really make sense.
+
+A schema may define section types which are \emph{abstract}; these
+cannot be used directly in a configuration, but multiple concrete
+section types can be defined which \emph{implement} the abstract
+types. Wherever the application allows an abstract type to be used,
+any concrete type which implements that abstract type can be used in
+an actual configuration.
+
+The \keyword{\%import} directive allows loading schema components
+which provide alternate concrete section types which implement the
+abstract types defined by the application. This allows third-party
+implementations of abstract types to be used in place of or in
+addition to implementations provided with the application.
+
+Consider an example application application which supports logging in
+the same way Zope 2 does. There are some parameters which configure
+the general behavior of the logging mechanism, and an arbitrary number
+of \emph{log handlers} may be specified to control how the log
+messages are handled. Several log handlers are provided by the
+application. Here is an example logging configuration:
+
+\begin{verbatim}
+<eventlog>
+ level verbose
+
+ <logfile>
+ path /var/log/myapp/events.log
+ </logfile>
+</eventlog>
+\end{verbatim}
+
+A third-party extension may provide a log handler to send
+high-priority alerts the system administrator's text pager or
+SMS-capable phone. All that's needed is to install the implementation
+so it can be imported by Python, and modify the configuration:
+
+\begin{verbatim}
+%import my.pager.loghandler
+
+<eventlog>
+ level verbose
+
+ <logfile>
+ path /var/log/myapp/events.log
+ </logfile>
+
+ <pager>
+ number 1-800-555-1234
+ message Something broke!
+ </pager>
+</eventlog>
+\end{verbatim}
\subsection{Textual Substitution in Values}
@@ -281,25 +331,46 @@
multikey)*}
Document element for a \module{ZConfig} schema.
+ \begin{attributedesc}{extends}{\datatype{space-separated-url-references}}
+ A list of URLs of base schemas from which this section type will inherit key,
+ section, and section type declarations. If omitted, this schema
+ is defined using only the keys, sections, and section types contained within
+ the \element{schema} element.
+ \end{attributedesc}
+
\begin{attributedesc}{datatype}{\datatype{basic-key}
or \datatype{dotted-name}}
The data type converter which will be applied to the value of this
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.
+ if set. If any base schemas are listed in the \attribute{extends}
+ attribute, the default value for this attribute comes from the base
+ schemas. If the base schemas all use the same \attribute{datatype}, then
+ that data type will be the default value for the extending schema. If
+ there are no base schemas, the default value is \datatype{null}, which
+ means that the \module{ZConfig} section object will be used unconverted.
+ If the base schemas have different \attribute{datatype} definitions, you
+ must explicitly define the \attribute{datatype} in the extending schema.
\end{attributedesc}
\begin{attributedesc}{handler}{\datatype{basic-key}}
\end{attributedesc}
- \begin{attributedesc}{keytype}{\datatype{basic-key}}
+ \begin{attributedesc}{keytype}{\datatype{basic-key}
+ or \datatype{dotted-name}}
The data type converter which will be applied to keys found in
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. 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}.
+ if set. If any base schemas are listed in the \attribute{extends}
+ attribute, the default value for this attribute comes from the base
+ schemas. If the base schemas all use the same \attribute{keytype}, then
+ that key type will be the default value for the extending schema. If there
+ are no base schemas, the default value is \datatype{basic-key}. If the
+ base schemas have different \attribute{keytype} definitions, you must
+ explicitly define the \attribute{keytype} in the extending schema.
\end{attributedesc}
\begin{attributedesc}{prefix}{\datatype{dotted-name}}
@@ -365,7 +436,7 @@
acquires all key and section declarations. This type does
\emph{not} automatically implement any abstract section type
implemented by the named section type. If omitted, this section
- is defined with only the keys are sections contained within the
+ is defined with only the keys and sections contained within the
\element{sectiontype} element.
\end{attributedesc}
@@ -399,13 +470,15 @@
\end{elementdesc}
\begin{elementdesc}{import}{EMPTY}
- Import a schema component.
- Exactly one of the two possible attributes must be specified.
+ Import a schema component. Exactly one of the attributes
+ \attribute{package} and \attribute{src} must be specified.
\begin{attributedesc}{file}{file name without directory information}
Name of the component file within a package; if not specified,
\file{component.xml} is used. This may only be given when
- \attribute{package} is used.
+ \attribute{package} is used. (The \file{component.xml} file is
+ always used when importing via \keyword{\%import} from a
+ configuration file.)
\end{attributedesc}
\begin{attributedesc}{package}{\datatype{dotted-name}}
@@ -632,17 +705,19 @@
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
-include additional types in application-provided abstract types.
+section types.
Components are identified using a dotted-name, similar to a Python
module name. For example, one component may be \code{zodb.storage}.
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.
+Python packages. The component definition is normally stored in the
+file \file{component.xml}; an alternate filename may be specified
+using the \attribute{file} attribute of the \element{import} element.
+Components imported using the \keyword{\%import} keyword from a
+configuration file must be named \file{component.xml}.
+The component defines the types provided by that component; it must
+have a \element{component} element as the document element.
The following element is used as the document element for schema
components. Note that schema components do not allow keys and
@@ -1259,7 +1334,5 @@
schema:
\verbatiminput{schema.dtd}
-
-%\input{oldapi}
\end{document}
=== Removed File Zope/lib/python/ZConfig/doc/oldapi.tex ===
More information about the Zodb-checkins
mailing list