[Zodb-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}