zope.configuration.xmlconfig

Support for the XML configuration file format

Note, for a detailed description of the way that conflicting configuration actions are resolved, see the detailed example in test_includeOverrides in tests/test_xmlconfig.py

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

Bases: object

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
'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)

Bases: xml.sax.handler.ContentHandler

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'
>>> f.close()

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'
>>> f.close()

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.

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.

Implementation:zope.schema.NativeStringLine Read Only:False Required:False Default Value:None Allowed Type:str

file

Configuration file name

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

Implementation:zope.schema.NativeStringLine Read Only:False Required:False Default Value:None Allowed Type:str

package

Include or exclude package

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

Implementation:zope.configuration.fields.GlobalObject Read Only:False Required:False Default Value:None

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

Include a zcml file

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. Conflicting actions added by the named file or files are resolved before this directive completes.

Caution

If you do not specify a file, then the default file of configure.zcml will be used. A common use is to set file to overrides.zcml.

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)

Bases: object

Provide high-level handling of configuration files.

See examples in tests/text_xmlconfig.py

zope.configuration.xmlconfig.testxmlconfig(file)

xmlconfig that doesn’t raise configuration errors

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