\documentclass{howto} \title{ZConfig Package Reference} %\date{\today} %\release{0.00} \author{Zope Corporation} \authoraddress{ Lafayette Technology Center\\ 513 Prince Edward Street\\ Fredericksburg, VA 22401\\ \url{http://www.zope.com/} } \begin{document} \maketitle \begin{abstract} \noindent This document describes the syntax and API used in configuration files for components of a Zope installation written by Zope Corporation. This configuration mechanism is itself configured using a schema specification written in XML. \begin{notice}[warning] 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. \end{notice} \end{abstract} \tableofcontents \section{Introduction \label{intro}} Zope uses a common syntax and API for configuration files designed for software components written by Zope Corporation. Third-party software which is also part of a Zope installation may use a different syntax, though any software is welcome to use the syntax used by Zope Corporation. Any software written in Python is free to use the \module{ZConfig} software to load such configuration files in order to 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. \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}} Like the \ulink{\module{ConfigParser}} {http://www.python.org/doc/current/lib/module-ConfigParser.html} format, this format supports key-value pairs arranged in sections. Unlike the \module{ConfigParser} format, sections are typed and can be organized hierarchically, 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. 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. 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. Comments can be added on lines by themselves. A comment has a \character{\#} as the first non-space character and extends to the end of the line: \begin{verbatim} # This is a comment \end{verbatim} An inclusion is expressed like this: \begin{verbatim} %include defaults.conf \end{verbatim} The resource to be included can be specified by a relative or absolute URL, resolved relative to the URL of the resource the \keyword{\%include} directive is located in. A key-value pair is expressed like this: \begin{verbatim} key value \end{verbatim} The key may include any non-white characters except for parentheses. The value contains all the characters between the key and the end of the line, with surrounding whitespace removed. Since comments must be on lines by themselves, the \character{\#} character can be part of a value: \begin{verbatim} key value # still part of the value \end{verbatim} Sections may be either empty or non-empty. An empty section may be used to provide an alias for another section. A non-empty section starts with a header, contains configuration data on subsequent lines, and ends with a terminator. The header for a non-empty section has this form (square brackets denote optional parts): \begin{alltt} <\var{section-type} \optional{\var{name}} \optional{(\var{basename})} > \end{alltt} \var{section-type}, \var{name}, and \var{basename} all have the same syntactic constraints as key names. The terminator looks like this: \begin{alltt} </\var{section-type}> \end{alltt} The configuration data in a non-empty section consists of a sequence of one or more key-value pairs and sections. For example: \begin{verbatim} <my-section> key-1 value-1 key-2 value-2 <another-section> key-3 value-3 </another-section> </my-section> \end{verbatim} (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 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: \begin{alltt} <\var{section-type} \optional{\var{name}} \optional{(\var{basename})} /> \end{alltt} \subsection{Textual Substitution in Values} \module{ZConfig} provides a limited way to re-use portions of a value using simple string substitution. To use this facility, define named bits of replacement text using the \keyword{\%define} directive, and reference these texts from values. The syntax for \keyword{\%define} is: \begin{alltt} %define \var{name} \optional{\var{value}} \end{alltt} The value of \var{name} must be a sequence of letters, digits, and underscores, and may not start with a digit; the namespace for these names is separate from the other namespaces used with \module{ZConfig}, and is case-insensitive. If \var{value} is omitted, it will be the empty string. If given, there must be whitespace between \var{name} and \var{value}; \var{value} will not include any whitespace on either side, just like values from key-value 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. References to defined names from configuration values use the syntax described for the \refmodule{ZConfig.substitution} module. Configuration values which include a \character{\$} as part of the 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. For example, the value for the \code{key} will evaluate to \code{value}: \begin{verbatim} %define name value key $name \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 \code{datatype} attribute on \code{key}, \code{multikey}, \code{schema}, \code{section}, and \code{multisection} elements. Applications may extend the set of datatypes by calling the \method{register()} method of the data type regsitry being used or by using Python dotted-names to refer to conversion routines defined in code. The following datatypes are provided by the default type registry. \begin{definitions} \term{basic-key} The default data type for a key in a ZConfig configuration file. The result of conversion is always lower-case, and matches the regular expression \regexp{[a-z][-._a-z0-9]*}. \term{boolean} Convert a human-friendly string to a boolean value. The names \code{yes}, \code{on}, and \code{true} convert to \constant{True}, while \code{no}, \code{off}, and \code{false} convert to \constant{False}. Comparisons are case-insensitive. All other input strings are disallowed. \term{byte-size} A specification of a size, with byte multiplier suffixes (for example, \samp{128MB}). Suffixes are case insensitive and may be ``KB'', ``MB'', or ``GB''. \term{constructor} Parse value in the form \samp{fn('1', '2', kw1='a', kw2='b')} into a 3-tuple where the first element is the string \code{'fn'}, the 2nd element is the list \code{['1','2']}, and the 3rd element is the dictionary \code{\{'kw1': 'a', 'kw2': 'b'\}}. This is useful when representing a Python-style constructor as a value. Python syntax rules are enforced, but only constants are allowed as positional and keyword arguments. The 3-tuple is returned. \term{existing-dirpath} Validates that the directory portion of a pathname exists. For example, if the value provided is \file{/foo/bar}, \file{/foo} must be an existing directory. No conversion is performed. \term{existing-directory} Validates that a directory by the given name exists on the local filesystem. No conversion is performed. \term{existing-file} Validates that a file by the given name exists. No conversion is performed. \term{existing-path} Validates that a path (file, directory, or symlink) by the given name exists on the local filesystem. No conversion is performed. \term{float} A Python float. \code{Inf}, \code{-Inf}, and \code{NaN} are not allowed. \term{identifier} Any valid Python identifier. \term{inet-address} An internet address expressed as a \code{(\var{hostname}, \var{port})} pair. If only the port is specified, an empty string will be returned for \var{hostname}. If the port is omitted, \code{None} will be returned for \var{port}. \term{integer} Convert a value to an integer. This will be a Python \class{int} if the value is in the range allowed by \class{int}, otherwise a Python \class{long} is returned. \term{ipaddr-or-hostname} Validates a valid IP address or hostname. If the first character is a digit, the value is assumed to be an IP address. If the first character is not a digit, the value is assumed to be a hostname. No conversion is performed. \term{key-value} Parse a value in the form \code{'A B'} into the list \code{['A', 'B']}. Returns the list. \term{locale} Any valid locale specifier accepted by the available \function{locale.setlocale()} function. Be aware that only the \code{'C'} locale is supported on some platforms. \term{logging-level} A logging level usable by the \module{logging} package. Valid values are the names \code{critical}, \code{fatal}, \code{error}, \code{warn}, \code{info}, \code{debug}, and \code{all}, as well as integers in the range [0..50]. Converted values are always expressed as integers. \term{null} No conversion is performed; the value passed in is the value returned. This is the default data type for section values. \term{port-number} Returns a valid port number as an integer. Validity does not imply that any particular use may be made of the port, however. For example, port number lower than 1024 generally cannot be bound by non-root users. \term{socket-address} 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 string, this implies that it will be checked to be simple 7-bit \ASCII. This is the default data type for key values in configuration files. \term{time-interval} A specification of a time interval, with multiplier suffixes, e.g. 12h. Suffixes are case insensitive and may be ``s'' (seconds), ``m'' (minutes), ``h'' (hours), or ``d'' (days). \end{definitions} \section{\module{ZConfig} --- Basic configuration support} \declaremodule{}{ZConfig} \modulesynopsis{Configuration package.} The main \module{ZConfig} package exports these convenience functions: \begin{funcdesc}{loadConfig}{schema, url} Load and return a configuration from a URL or pathname given by \var{url}. \var{url} may be a URL, absolute pathname, or relative pathname. Fragment identifiers are not supported. \var{schema} is a referennce to a schema loaded by \function{loadSchema()} or \function{loadSchemaFile()}. The return value is a tuple containing the configuration object and a composite handler that, when called with a name-to-handler mapping, calls all the handlers for the configuration. % XXX need to talk about handlers and the schema definitions still! \end{funcdesc} \begin{funcdesc}{loadConfigFile}{schema, 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. \var{schema} is a referennce to a schema loaded by \function{loadSchema()} or \function{loadSchemaFile()}. The return value is a tuple containing the configuration object and a composite handler that, when called with a name-to-handler mapping, calls all the handlers for the configuration. % XXX need to talk about handlers and the schema definitions still! \end{funcdesc} \begin{funcdesc}{loadSchema}{url} Load a schema definition from the URL \var{url}. The resulting schema object can be passed to \function{loadConfig()} or \function{loadConfigFile()}. The schema object may be used as many times as needed. \end{funcdesc} \begin{funcdesc}{loadSchemaFile}{file\optional{, url}} Load a schema definition from the open file object \var{file}. If \var{url} is given and not \code{None}, it should be the URL of resource represented by \var{file}. If \var{url} is ommitted or \code{None}, a URL may be computed from the \member{name} attrigbute of \var{file}, if present. The resulting schema object can be passed to \function{loadConfig()} or \function{loadConfigFile()}. The schema object may be used as many times as needed. \end{funcdesc} The following exceptions are defined by this package: \begin{excdesc}{ConfigurationError} Base class for exceptions specific to the \module{ZConfig} package. All instances provide a \member{message} attribute that describes the specific error. \end{excdesc} \begin{excdesc}{ConfigurationSyntaxError} Exception raised when a configuration source does not conform to the allowed syntax. In addition to the \member{message} attribute, exceptions of this type offer the \member{url} and \member{lineno} attributes, which provide the URL and line number at which the error was detected. \end{excdesc} \begin{excdesc}{ConfigurationTypeError} \end{excdesc} \begin{excdesc}{ConfigurationMissingSectionError} Raised when a requested named section is not available. \end{excdesc} \begin{excdesc}{ConfigurationConflictingSectionError} Raised when a request for a section cannot be fulfilled without 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 \member{colno}, which provide the source URL, the line number, and the column number at which the error was detected. These attributes may be \code{None} in some cases. \end{excdesc} \begin{excdesc}{SubstitutionReplacementError} Raised when the source text contains references to names which are not defined in \var{mapping}. The attributes \member{source} and \member{name} provide the complete source text and the name (converted to lower case) for which no replacement is defined. \end{excdesc} \begin{excdesc}{SubstitutionSyntaxError} Raised when the source text contains syntactical errors. \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 about the application context at all; the \function{loadURL()} function in the \module{ZConfig} module uses the default context implementation to glue everything together. 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 overridable 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 taht 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} \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 \code{True} if \var{key} has an associated value, otherwise returns \code{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 descendents 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} \section{\module{ZConfig.datatypes} --- Default data type registry} \declaremodule{}{ZConfig.datatypes} \modulesynopsis{Default implementation of a data type registry} The \module{ZConfig.datatypes} module provides the implementation of the default data type registry and all the standard data types supported by \module{ZConfig}. A number of convenience classes are also provided to assist in the creation of additional datatypes. A \dfn{datatype registry} is an object that provides conversion functions for data types. The interface for a registry is fairly simple. A \dfn{conversion function} is any callable object that accepts a single argument and returns a suitable value, or raises an exception if the input value is not acceptable. \exception{ValueError} is the preferred exception for disallowed inputs, but any other exception will be properly propogated. \begin{classdesc}{Registry}{\optional{stock}} Implementation of a simple type registry. If given, \var{stock} should be a mapping which defines the ``built-in'' data types for the registry; if omitted or \code{None}, the standard set of data types is used (see section~\ref{standard-datatypes}, ``Standard \module{ZConfig} Datatypes''). \end{classdesc} \class{Registry} objects have the following methods: \begin{methoddesc}{get}{name} Return the type conversion routine for \var{name}. If the conversion function cannot be found, an (unspecified) exception is 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 rest of \module{ZConfig} requires. \end{methoddesc} \begin{methoddesc}{register}{name, conversion} Registery the data type name \var{name} to use the conversion function \var{conversion}. If \var{name} is already registered or provided as a stock data type, \exception{ValueError} is raised (this includes the case when \var{name} was found using the \method{search()} method). \end{methoddesc} \begin{methoddesc}{search}{name} This is a helper method for the default implementation of the \method{get()} method. If \var{name} is a Python dotted-name, this method loads the value for the name by dynamically importing the containing module and extracting the value of the name. The name must refer to a usable conversion function. \end{methoddesc} The following classes are provided to define conversion functions: \begin{classdesc}{MemoizedConversion}{conversion} Simple memoization for potentially expensive conversions. This conversion helper caches each successful conversion for re-use at a later time; failed conversions are not cached in any way, since it is difficult to raise a meaningful excpetion providing information about the specific failure. \end{classdesc} \begin{classdesc}{RangeCheckedConversion}{conversion\optional{, min\optional{, max}}} Helper that performs range checks on the result of another conversion. Values passed to instances of this conversion are converted using \var{conversion} and then range checked. \var{min} and \var{max}, if given and not \code{None}, are the inclusive endpoints of the allowed range. Values returned by \var{conversion} which lay outside the range described by \var{min} and \var{max} cause \exception{ValueError} to be raised. \end{classdesc} \begin{classdesc}{RegularExpressionConversion}{regex} Conversion that checks that the input matches the regular expression \var{regex}. If it matches, returns the input, otherwise raises \exception{ValueError}. \end{classdesc} \section{\module{ZConfig.loader} --- Resource loading support} \declaremodule{}{ZConfig.loader} \modulesynopsis{Support classes for resource loading} This module provides some helper classes used by the primary APIs exported by the \module{ZConfig} package. These classes may be useful for some applications, especially applications that want to use a non-default data type registry. \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}, \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}{} Base class for loader objects. This should not be instantiated directly, as the \method{loadResource()} method must be overridden for the instance to be used via the public API. \end{classdesc} \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}} Loader that loads schema instances. All schema loaded by a \class{SchemaLoader} will use the same data type registry. If \var{registry} is provided and not \code{None}, it will be used, 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} Loader objects provide a general public interface, an inteface which subclasses must implement, and some utility methods. The following methods provide the public interface: \begin{methoddesc}[loader]{loadURL}{url} Open and load a resource specified by the URL \var{url}. This method uses the \method{loadResource()} method to perform the actual load, and returns whatever that method returns. \end{methoddesc} \begin{methoddesc}[loader]{loadFile}{file\optional{, url}} Load from an open file object, \var{file}. If given and not \code{None}, \var{url} should be the URL of the resource represented by \var{file}. If omitted or \code{None}, the \member{name} attribute of \var{file} is used to compute a \code{file:} URL, if present. This method uses the \method{loadResource()} method to perform the actual load, and returns whatever that method returns. \end{methoddesc} The following method must be overridden by subclasses: \begin{methoddesc}[loader]{loadResource}{resource} Subclasses of \class{BaseLoader} must implement this method to actually load the resource and return the appropriate application-level object. \end{methoddesc} The following methods can be used as utilities: \begin{methoddesc}[loader]{normalizeURL}{url-or-path} Return a URL for \var{url-or-path}. If \var{url-or-path} refers to an existing file, the corresponding \code{file:} URL is returned. Otherwise \var{url-or-path} is checked for sanity: if it does not have a schema, \exception{ValueError} is raised, and if it does have a fragment identifier, \exception{ConfigurationError} is raised. \end{methoddesc} \begin{methoddesc}[loader]{openResource}{url} Returns a resource object that represents the URL \var{url}. The URL is opened using the \function{urllib2.urlopen()} function, and the returned resource object is created using \method{createResource()}. \end{methoddesc} \begin{methoddesc}[loader]{createResource}{file, url} Returns a resource object for an open file and URL, given as \var{file} and \var{url}, respectively. This may be overridden by a subclass if an alternate resource implementation is desired. \end{methoddesc} \section{\module{ZConfig.substitution} --- String substitution} \declaremodule{}{ZConfig.substitution} \modulesynopsis{Shell-style string substitution helper.} This module provides a basic substitution facility similar to that found in the Bourne shell (\program{sh} on most \UNIX{} platforms). The replacements supported by this module include: \begin{tableiii}{l|l|c}{code}{Source}{Replacement}{Notes} \lineiii{\$\$}{\code{\$}}{(1)} \lineiii{\$\var{name}}{The result of looking up \var{name}}{(2)} \lineiii{\$\{\var{name}\}}{The result of looking up \var{name}}{} \end{tableiii} \noindent Notes: \begin{description} \item[(1)] This is different from the Bourne shell, which uses \code{\textbackslash\$} to generate a \character{\$} in the result text. This difference avoids having as many special characters in the syntax. \item[(2)] Any character which immediately follows \var{name} may not be a valid character in a name. \end{description} In each case, \var{name} is a non-empty sequence of alphanumeric and underscore characters not starting with a digit. If there is not a replacement for \var{name}, the exception \exception{SubstitutionReplacementError} is raised. Note that the lookup is expected to be case-insensitive; this module will always use a lower-case version of the name to perform the query. This module provides these functions: \begin{funcdesc}{substitute}{s, mapping} Substitute values from \var{mapping} into \var{s}. \var{mapping} can be a \class{dict} or any type that supports the \method{get()} method of the mapping protocol. Replacement values are copied into the result without further interpretation. Raises \exception{SubstitutionSyntaxError} if there are malformed constructs in \var{s}. \end{funcdesc} \begin{funcdesc}{isname}{s} Returns \code{True} if \var{s} is a valid name for a substitution text, otherwise returns \code{False}. \end{funcdesc} \subsection{Examples} \begin{verbatim} >>> from ZConfig.substitution import substitute >>> d = {'name': 'value', ... 'top': '$middle', ... 'middle' : 'bottom'} >>> >>> substitute('$name', d) 'value' >>> substitute('$top', d) '$middle' \end{verbatim} \end{document}