ZConfig — Basic configuration support

Functions

The main ZConfig package exports these convenience functions:

ZConfig.loadConfig(schema, url, overrides=())

Load and return a configuration from a URL or pathname given by url.

url may be a URL, absolute pathname, or relative pathname. Fragment identifiers are not supported. schema is a reference to a schema loaded by loadSchema() or 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.

The optional overrides argument represents information derived from command-line arguments. If given, it must be either a sequence of value specifiers, or None. A “value specifier” is a string of the form optionpath=value, for example, some/path/to/key=value.

See also

ExtendedConfigLoader.addOption()
For information on the format of value specifiers.
ConfigLoader
For information about loading configs.
BaseLoader.loadURL()
For information about the format of url
ZConfig.loadConfigFile(schema, file, url=None, overrides=())

Load and return a configuration from an opened file object.

If url is omitted, one will be computed based on the name attribute of file, if it exists. If no URL can be determined, all %include statements in the configuration must use absolute URLs. schema is a reference to a schema loaded by loadSchema() or 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. The overrides argument is the same as for the loadConfig() function.

See also

ConfigLoader, BaseLoader.loadFile(), ExtendedConfigLoader.addOption()

ZConfig.loadSchema(url)

Load a schema definition from the URL url.

url may be a URL, absolute pathname, or relative pathname. Fragment identifiers are not supported.

The resulting schema object can be passed to loadConfig() or loadConfigFile(). The schema object may be used as many times as needed.

See also

SchemaLoader, BaseLoader.loadURL()

ZConfig.loadSchemaFile(file, url=None)

Load a schema definition from the open file object file.

If url is given and not None, it should be the URL of resource represented by file. If url is omitted or None, a URL may be computed from the name attribute of file, if present. The resulting schema object can be passed to loadConfig() or loadConfigFile(). The schema object may be used as many times as needed.

See also

SchemaLoader, BaseLoader.loadFile()

Exceptions

The following exceptions are defined by this package:

exception ZConfig.ConfigurationError

Bases: exceptions.Exception

Base class for exceptions specific to the ZConfig package.

All instances provide a message attribute that describes the specific error, and a url attribute that gives the URL of the resource the error was located in, or None.

exception ZConfig.ConfigurationSyntaxError

Exception raised when a configuration source does not conform to the allowed syntax.

In addition to the message and url attributes, exceptions of this type offer the lineno attribute, which provides the line number at which the error was detected.

exception ZConfig.DataConversionError

Bases: ZConfig.ConfigurationError, exceptions.ValueError

Raised when a data type conversion fails with ValueError.

This exception is a subclass of both ConfigurationError and ValueError. The str() of the exception provides the explanation from the original ValueError, and the line number and URL of the value which provoked the error. The following additional attributes are provided:

colno
column number at which the value starts, or None
exception
the original ValueError instance
lineno
line number on which the value starts
message
str() returned by the original ValueError
value
original value passed to the conversion function
url
URL of the resource providing the value text
exception ZConfig.SchemaError

Raised when a schema contains an error.

This exception type provides the attributes url, lineno, and colno, which provide the source URL, the line number, and the column number at which the error was detected. These attributes may be None in some cases.

exception ZConfig.SchemaResourceError

Bases: ZConfig.SchemaError

Raised when there’s an error locating a resource required by the schema.

Instances of this exception class add the attributes filename, package, and path, which hold the filename searched for within the package being loaded, the name of the package, and the __path__ attribute of the package itself (or None if it isn’t a package or could not be imported).

exception ZConfig.SubstitutionReplacementError

Bases: ZConfig.ConfigurationSyntaxError, exceptions.LookupError

Raised when the source text contains references to names which are not defined in mapping.

The attributes source and name provide the complete source text and the name (converted to lower case) for which no replacement is defined.

exception ZConfig.SubstitutionSyntaxError

Raised when interpolation source text contains syntactical errors.

Basic Usage

The simplest use of 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:

import os
import sys
import ZConfig

try:
    myfile = __file__
except NameError:
    myfile = os.path.realpath(sys.argv[0])

mydir = os.path.dirname(myfile)

schema = ZConfig.loadSchema(os.path.join(mydir, 'schema.xml'))
conf, handler = ZConfig.loadConfig(schema, sys.argv[1])

If the schema file contained this schema:

<schema>
  <key name='server' required='yes'/>
  <key name='attempts' datatype='integer' default='5'/>
</schema>

and the file specified on the command line contained this text:

# sample configuration

server www.example.com

then the configuration object conf loaded above would have two attributes, server with the value 'www.example.com' and attempts with the value 5.