zope.configuration.xmlconfig

class zope.configuration.xmlconfig.ZopeXMLConfigurationError(info, etype, evalue)

Zope XML Configuration error

These errors are wrappers for other errors. They include configuration info and the wrapped error type and value.

Example

>>> from zope.configuration.xmlconfig import ZopeXMLConfigurationError
>>> v = ZopeXMLConfigurationError("blah", AttributeError, "xxx")
>>> print v
'blah'
    AttributeError: xxx

class zope.configuration.xmlconfig.ZopeSAXParseException(v)

Sax Parser errors, reformatted in an emacs friendly way

Example

>>> from zope.configuration.xmlconfig import ZopeSAXParseException
>>> v = ZopeSAXParseException("foo.xml:12:3:Not well formed")
>>> print v
File "foo.xml", line 12.3, Not well formed

class zope.configuration.xmlconfig.ParserInfo(file, line, column)

Information about a directive based on parser data

This includes the directive location, as well as text data contained in the directive.

Example

>>> from zope.configuration.xmlconfig import ParserInfo
>>> info = ParserInfo('tests//sample.zcml', 1, 0)
>>> info
File "tests//sample.zcml", line 1.0

>>> print info
File "tests//sample.zcml", line 1.0

>>> info.characters("blah\\n")
>>> info.characters("blah")
>>> info.text
u'blah\\nblah'

>>> info.end(7, 0)
>>> info
File "tests//sample.zcml", line 1.0-7.0

>>> print info
File "tests//sample.zcml", line 1.0-7.0
  <configure xmlns='http://namespaces.zope.org/zope'>
    <!-- zope.configure -->
    <directives namespace="http://namespaces.zope.org/zope">
      <directive name="hook" attributes="name implementation module"
         handler="zope.configuration.metaconfigure.hook" />
    </directives>
  </configure>

class zope.configuration.xmlconfig.ConfigurationHandler(context, testing=False)

Interface to the xml parser

Translate parser events into calls into the configuration system.

evaluateCondition(expression)

Evaluate a ZCML condition.

expression is a string of the form “verb arguments”.

Currently the supported verbs are have, not-have, installed and not-installed.

The have and not-have verbs each take one argument: the name of a feature:

>>> from zope.configuration.config import ConfigurationContext
>>> from zope.configuration.xmlconfig import ConfigurationHandler
>>> context = ConfigurationContext()
>>> context.provideFeature('apidoc')
>>> c = ConfigurationHandler(context, testing=True)
>>> c.evaluateCondition("have apidoc")
True
>>> c.evaluateCondition("not-have apidoc")
False
>>> c.evaluateCondition("have onlinehelp")
False
>>> c.evaluateCondition("not-have onlinehelp")
True

Ill-formed expressions raise an error:

>>> c.evaluateCondition("want apidoc")
Traceback (most recent call last):
  ...
ValueError: Invalid ZCML condition: 'want apidoc'

>>> c.evaluateCondition("have x y")
Traceback (most recent call last):
  ...
ValueError: Only one feature allowed: 'have x y'

>>> c.evaluateCondition("have")
Traceback (most recent call last):
  ...
ValueError: Feature name missing: 'have'

The installed and not-installed verbs each take one argument: the dotted name of a pacakge.

If the pacakge is found, in other words, can be imported, then the condition will return true / false:

>>> context = ConfigurationContext()
>>> c = ConfigurationHandler(context, testing=True)
>>> c.evaluateCondition('installed zope.interface')
True
>>> c.evaluateCondition('not-installed zope.interface')
False
>>> c.evaluateCondition('installed zope.foo')
False
>>> c.evaluateCondition('not-installed zope.foo')
True

Ill-formed expressions raise an error:

>>> c.evaluateCondition("installed foo bar")
Traceback (most recent call last):
  ...
ValueError: Only one package allowed: 'installed foo bar'

>>> c.evaluateCondition("installed")
Traceback (most recent call last):
  ...
ValueError: Package name missing: 'installed'

zope.configuration.xmlconfig.processxmlfile(file, context, testing=False)

Process a configuration file

See examples in tests/test_xmlconfig.py

zope.configuration.xmlconfig.openInOrPlain(filename)

Open a file, falling back to filename.in.

If the requested file does not exist and filename.in does, fall back to filename.in. If opening the original filename fails for any other reason, allow the failure to propogate.

For example, the tests/samplepackage dirextory has files:

• configure.zcml
• configure.zcml.in
• foo.zcml.in

If we open configure.zcml, we’ll get that file:

>>> import os
>>> from zope.configuration.xmlconfig import __file__
>>> from zope.configuration.xmlconfig import openInOrPlain
>>> here = os.path.dirname(__file__)
>>> path = os.path.join(here, 'tests', 'samplepackage', 'configure.zcml')
>>> f = openInOrPlain(path)
>>> f.name[-14:]
'configure.zcml'

But if we open foo.zcml, we’ll get foo.zcml.in, since there isn’t a foo.zcml:

>>> path = os.path.join(here, 'tests', 'samplepackage', 'foo.zcml')
>>> f = openInOrPlain(path)
>>> f.name[-11:]
'foo.zcml.in'

Make sure other IOErrors are re-raised. We need to do this in a try-except block because different errors are raised on Windows and on Linux.

>>> try:
...     f = openInOrPlain('.')
... except IOError:
...     print "passed"
... else:
...     print "failed"
passed

interface zope.configuration.xmlconfig.IInclude

The include, includeOverrides and exclude directives

These directives allows you to include or preserve including of another ZCML file in the configuration. This enables you to write configuration files in each package and then link them together.

file

Configuration file name

The name of a configuration file to be included/excluded, relative to the directive containing the including configuration file.

files

Configuration file name pattern

The names of multiple configuration files to be included/excluded, expressed as a file-name pattern, relative to the directive containing the including or excluding configuration file. The pattern can include:

• * matches 0 or more characters
• ? matches a single character
• [<seq>] matches any character in seq
• [!<seq>] matches any character not in seq

The file names are included in sorted order, where sorting is without regard to case.

package

Include or exclude package

Include or exclude the named file (or configure.zcml) from the directory of this package.

zope.configuration.xmlconfig.include(_context, file=None, package=None, files=None)

Include a zcml file

See examples in tests/text_xmlconfig.py

zope.configuration.xmlconfig.exclude(_context, file=None, package=None, files=None)

Exclude a zcml file

This directive should be used before any ZML that includes configuration you want to exclude.

zope.configuration.xmlconfig.includeOverrides(_context, file=None, package=None, files=None)

Include zcml file containing overrides

The actions in the included file are added to the context as if they were in the including file directly.

See the detailed example in test_includeOverrides in tests/text_xmlconfig.py

zope.configuration.xmlconfig.registerCommonDirectives(context)

zope.configuration.xmlconfig.file(name, package=None, context=None, execute=True)

Execute a zcml file

zope.configuration.xmlconfig.string(s, context=None, name='<string>', execute=True)

Execute a zcml string

class zope.configuration.xmlconfig.XMLConfig(file_name, module=None)

Provide high-level handling of configuration files.

See examples in tests/text_xmlconfig.py

zope.configuration.xmlconfig.xmlconfig(file, testing=False)

zope.configuration.xmlconfig.testxmlconfig(file)

xmlconfig that doesn’t raise configuration errors

This is useful for testing, as it doesn’t mask exception types.