[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