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()
orloadSchemaFile()
.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 formoptionpath=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 byloadSchema()
orloadSchemaFile()
.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.
-
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()
orloadConfigFile()
. The schema object may be used as many times as needed.See also
-
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 orNone
, a URL may be computed from thename
attribute of file, if present. The resulting schema object can be passed toloadConfig()
orloadConfigFile()
. The schema object may be used as many times as needed.See also
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 aurl
attribute that gives the URL of the resource the error was located in, orNone
.
-
exception
ZConfig.
ConfigurationSyntaxError
¶ Exception raised when a configuration source does not conform to the allowed syntax.
In addition to the
message
andurl
attributes, exceptions of this type offer thelineno
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
andValueError
. Thestr()
of the exception provides the explanation from the originalValueError
, 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 originalValueError
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
, andcolno
, which provide the source URL, the line number, and the column number at which the error was detected. These attributes may beNone
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
, andpath
, which hold the filename searched for within the package being loaded, the name of the package, and the__path__
attribute of the package itself (orNone
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
andname
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
.