[Zope3-checkins] CVS: Zope/lib/python/ZConfig/doc - schema.dtd:1.2.2.1 Makefile:1.1.40.1 zconfig.tex:1.35.10.16

Fred L. Drake, Jr. fred@zope.com
Thu, 9 Jan 2003 14:28:21 -0500


Update of /cvs-repository/Zope/lib/python/ZConfig/doc
In directory cvs.zope.org:/tmp/cvs-serv3113/doc

Modified Files:
      Tag: zconfig-schema-devel-branch
	Makefile zconfig.tex 
Added Files:
      Tag: zconfig-schema-devel-branch
	schema.dtd 
Log Message:
Merge from the ZConfig HEAD.

=== Added File Zope/lib/python/ZConfig/doc/schema.dtd ===
<!-- DTD for ZConfig schema documents. -->

<!ELEMENT schema (description?, metadefault?, example?,
                  import*,
                  (sectiontype | sectiongroup)*,
                  (section | key | multisection | multikey)*)>
<!ATTLIST schema
          prefix     NMTOKEN  #IMPLIED
          handler    NMTOKEN  #IMPLIED
          keytype    NMTOKEN  #IMPLIED
          datatype   NMTOKEN  #IMPLIED>

<!ELEMENT component (description?, (sectiontype | sectiongroup)*)>
<!ATTLIST component
          prefix     NMTOKEN  #IMPLIED>

<!ELEMENT extension (description?, (sectiontype | sectiongroup)*)>
<!ATTLIST extension
          prefix     NMTOKEN  #IMPLIED>

<!ELEMENT import EMPTY>
<!ATTLIST import
          src        CDATA    #REQUIRED>

<!ELEMENT description (#PCDATA)*>
<!ELEMENT metadefault (#PCDATA)*>
<!ELEMENT example     (#PCDATA)*>

<!ELEMENT key (description?, metadefault?, example?)>
<!ATTLIST key
          name       NMTOKEN  #REQUIRED
          attribute  NMTOKEN  #IMPLIED
          datatype   NMTOKEN  #IMPLIED
          handler    NMTOKEN  #IMPLIED
          required   (yes|no) "no"
          default    CDATA    #IMPLIED>

<!ELEMENT multikey (description?, metadefault?, example?, default*)>
<!ATTLIST multikey
          name       NMTOKEN  #REQUIRED
          attribute  NMTOKEN  #IMPLIED
          datatype   NMTOKEN  #IMPLIED
          handler    NMTOKEN  #IMPLIED
          required   (yes|no) "no">

<!ELEMENT sectiontype (description?, (section | key)*)>
<!ATTLIST sectiontype
          type       NMTOKEN  #REQUIRED
          prefix     NMTOKEN  #IMPLIED
          keytype    NMTOKEN  #IMPLIED
          datatype   NMTOKEN  #IMPLIED
          group      NMTOKEN  #IMPLIED
          extends    NMTOKEN  #IMPLIED>

<!ELEMENT sectiongroup (description?, sectiontype+)>
<!ATTLIST sectiongroup
          type       NMTOKEN  #REQUIRED
          prefix     NMTOKEN  #IMPLIED>

<!ELEMENT section (description?)>
<!ATTLIST section
          name       NMTOKEN  #REQUIRED
          attribute  NMTOKEN  #IMPLIED
          type       NMTOKEN  #REQUIRED
          handler    NMTOKEN  #IMPLIED
          minOccurs  NMTOKEN  #IMPLIED
          maxOccurs  NMTOKEN  #IMPLIED>

<!ELEMENT multisection (description?)>
<!ATTLIST multisection
          name       NMTOKEN  #REQUIRED
          attribute  NMTOKEN  #IMPLIED
          type       NMTOKEN  #REQUIRED
          handler    NMTOKEN  #IMPLIED
          required   (yes|no) "no">


=== Zope/lib/python/ZConfig/doc/Makefile 1.1 => 1.1.40.1 ===
--- Zope/lib/python/ZConfig/doc/Makefile:1.1	Thu Oct 10 10:41:45 2002
+++ Zope/lib/python/ZConfig/doc/Makefile	Thu Jan  9 14:27:48 2003
@@ -1,4 +1,7 @@
 # Rules to convert the documentation to a single PDF file.
+#
+# See the README.txt file for information on the mkhowto program used
+# to generate the PDF and PostScript versions of the documentation.
 
 .PHONY:	default all pdf ps
 


=== Zope/lib/python/ZConfig/doc/zconfig.tex 1.35.10.15 => 1.35.10.16 ===
--- Zope/lib/python/ZConfig/doc/zconfig.tex:1.35.10.15	Fri Jan  3 14:59:56 2003
+++ Zope/lib/python/ZConfig/doc/zconfig.tex	Thu Jan  9 14:27:48 2003
@@ -24,7 +24,7 @@
 written in XML.
 
 \begin{notice}[warning]
-  ZConfig have changed a great deal since this document was initially
+  ZConfig has changed a great deal since this document was initially
   written, and parts of this have not yet been updated, though
   portions have been.  Please be patient as the documentation catches
   up.
@@ -47,7 +47,17 @@
 
 The \module{ZConfig} package has been tested with Python 2.1 and 2.2.
 Python 2.0 is not supported.
-It only relies on the Python standard library.
+\module{ZConfig} only relies on the Python standard library.
+
+Configurations which use \module{ZConfig} are described using
+\dfn{schema}.  A schema is a specification for the allowed structure
+and content of the configuration.  \module{ZConfig} schema are written
+using a small XML-based language.  The schema language allows the
+schema author to specify the names of the keys allowed at the top
+level and within sections, to define the types of sections which may
+be used (and where), the types of each values, whether a key or
+section must be specified or is optional, default values for keys, and
+whether a value can be given only once or repeatedly.
 
 
 \section{Configuration Syntax \label{syntax}}
@@ -204,10 +214,9 @@
 pairs.
 
 Names must be defined before they are used, and may not be
-re-defined.  All names are associated with the source text in which
-they are defined, so distinct sources which are referenced using
-\keyword{\%include} are not affected by
-definitions created by the resource being parsed.
+re-defined.  All resources being parsed as part of a configuration
+share a single namespace for defined names.  This means that resources
+which may be included more than once should not define any names.
 
 References to defined names from configuration values use the syntax
 described for the \refmodule{ZConfig.substitution} module.
@@ -215,8 +224,9 @@
 actual value will need to use \code{\$\$} to get a single
 \character{\$} in the result.
 
-The values of defined names are not processed in any way, and may not
-contain references to named definitions.
+The values of defined names are processed in the same way as
+configuration values, and may contain references to named
+definitions.
 
 For example, the value for the \code{key} will evaluate to
 \code{value}:
@@ -227,6 +237,46 @@
 \end{verbatim} %$ <-- bow to font-lock
 
 
+\section{Writing Configuration Schema \label{writing-schema}}
+
+XXX to be written
+
+
+\section{Libraries of Schema Components \label{schema-library}}
+
+XXX need more explanation
+
+\module{ZConfig} supports a library of extensible 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.
+
+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.
+Components are identified using a dotted-name, similar to a Python
+module name.  For example, one component may be \code{zodb.storage}.
+There is no relationship between the schema component namespace and
+the Python module namespace.
+
+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 \code{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 \code{extension} element as
+the document element.
+
+
 \section{Standard \module{ZConfig} Datatypes\label{standard-datatypes}}
 
 There are a number of data types which can be identified using the
@@ -335,12 +385,15 @@
   non-root users.
 
 \term{socket-address}
-  An address for a socket.  The converted value is a pair containing
-  the address family (\constant{AF_INET} or \constant{AF_UNIX}) in the
-  first part and the specific address in the second part.  If the
-  family is \constant{AF_UNIX}, the specific address will be a
-  pathname; if the family is \constant{AF_INET}, the second part will
-  be the result of the \strong{inet-address} conversion.
+  An address for a socket.  The converted value is an object providing
+  two attributes.  \member{family} specifies the address family
+  (\constant{AF_INET} or \constant{AF_UNIX}), with \code{None} instead
+  of \constant{AF_UNIX} on platforms that don't support it.  The
+  \member{address} attribute will be the address that should be passed
+  to the socket's \method{bind()} method.  If the family is
+  \constant{AF_UNIX}, the specific address will be a pathname; if the
+  family is \constant{AF_INET}, the second part will be the result of
+  the \strong{inet-address} conversion.
 
 \term{string}
   Returns the input value as a string.  If the source is a Unicode
@@ -434,6 +487,31 @@
   ambiguity.
 \end{excdesc}
 
+\begin{excdesc}{DataConversionError}
+  Raised when a data type conversion fails with
+  \exception{ValueError}.  This exception is a subclass of both
+  \exception{ConfigurationError} and \exception{ValueError}.  The
+  \function{str()} of the exception provides the explanation from the
+  original \exception{ValueError}, and the line number and URL of the
+  value which provoked the error.  The following additional attributes
+  are provided:
+
+  \begin{tableii}{l|l}{member}{Attribute}{Value}
+    \lineii{colno}
+           {column number at which the value starts, or \code{None}}
+    \lineii{exception}
+           {the original \exception{ValueError} instance}
+    \lineii{lineno}
+           {line number on which the value starts}
+    \lineii{message}
+           {\function{str()} returned by the original \exception{ValueError}}
+    \lineii{value}
+           {original value passed to the conversion function}
+    \lineii{url}
+           {URL of the resource providing the value text}
+  \end{tableii}
+\end{excdesc}
+
 \begin{excdesc}{SchemaError}
   Raised when a schema contains an error.  This exception type
   provides the attributes \member{url}, \member{lineno}, and
@@ -454,11 +532,68 @@
 \end{excdesc}
 
 
+\subsection{Basic Usage}
+
+The simplest use of \refmodule{ZConfig} is to load a configuration
+based on a schema stored in a file.  This example loads a
+configuration file specified on the command line using a schema in the
+same directory as the script:
+
+\begin{verbatim}
+import os
+import sys
+import ZConfig
+
+try:
+    myfile = __file__
+except NameError:
+    # really should follow symlinks here:
+    myfile = sys.argv[0]
+
+mydir = os.path.dirname(os.path.abspath(myfile))
+
+schema = ZConfig.loadSchema(os.path.join(mydir, 'schema.xml'))
+conf = ZConfig.loadConfig(schema, sys.argv[1])
+\end{verbatim}
+
+If the schema file contained this schema:
+
+\begin{verbatim}
+<schema>
+  <key name='server' required='yes'/>
+  <key name='attempts' datatype='integer' default='5'/>
+</schema>
+\end{verbatim}
+
+and the file specified on the command line contained this text:
+
+\begin{verbatim}
+# sample configuration
+
+server www.example.com
+\end{verbatim}
+
+then the configuration object \code{conf} loaded above would have two
+attributes:
+
+\begin{tableii}{l|l}{member}{Attribute}{Value}
+  \lineii{server}{\code{'www.example.com'}}
+  \lineii{attempts}{\code{5}}
+\end{tableii}
+
+
 \section{\module{ZConfig.Context} --- Application context}
 
 \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 not need to worry
@@ -567,8 +702,17 @@
 \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.
+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
@@ -762,7 +906,7 @@
   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 \module{ZConfig.schema} module requires.
+  This is the only method the rest of \module{ZConfig} requires.
 \end{methoddesc}
 
 \begin{methoddesc}{register}{name, conversion}
@@ -820,13 +964,14 @@
 for some applications, especially applications that want to use a
 non-default data type registry.
 
-\begin{classdesc}{Resource}{file, url}
+\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} and \member{url} 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}.
+  \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}{}
@@ -835,11 +980,14 @@
   for the instance to be used via the public API.
 \end{classdesc}
 
-\begin{classdesc}{ConfigLoader}{schema}
+\begin{classdesc}{ConfigLoader}{schema\optional{, library}}
   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.
+  The schema component directory is stored in the directory identified
+  by \var{library}, which defaults to \constant{LIBRARY_DIR} if
+  omitted or \code{None}.
 \end{classdesc}
 
 \begin{classdesc}{SchemaLoader}{\optional{registry}}
@@ -849,6 +997,10 @@
   otherwise an instance of \class{ZConfig.datatypes.Registry} will be
   used.
 \end{classdesc}
+
+\begin{datadesc}{LIBRARY_DIR}
+  Default directory for the schema component library.
+\end{datadesc}
 
 
 \subsection{Loader Objects}