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)[source]

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)[source]

Bases: xml.sax.handler.ContentHandler

Interface to the XML parser

Translate parser events into calls into the configuration system.

characters(text)[source]

Receive notification of character data.

The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity so that the Locator provides useful information.

endElementNS(name, qname)[source]

Signals the end of an element in namespace mode.

The name parameter contains the name of the element type, just as with the startElementNS event.

evaluateCondition(expression)[source]

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'
setDocumentLocator(locator)[source]

Called by the parser to give the application a locator for locating the origin of document events.

SAX parsers are strongly encouraged (though not absolutely required) to supply a locator: if it does so, it must supply the locator to the application by invoking this method before invoking any of the other methods in the DocumentHandler interface.

The locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application will use this information for reporting its own errors (such as character content that does not match an application’s business rules). The information returned by the locator is probably not sufficient for use with a search engine.

Note that the locator will return correct information only during the invocation of the events in this interface. The application should not attempt to use it at any other time.

startElementNS(name, qname, attrs)[source]

Signals the start of an element in namespace mode.

The name parameter contains the name of the element type as a (uri, localname) tuple, the qname parameter the raw XML 1.0 name used in the source document, and the attrs parameter holds an instance of the Attributes class containing the attributes of the element.

The uri part of the name tuple is None for elements which have no namespace.

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

Process a configuration file

See examples in tests/test_xmlconfig.py

zope.configuration.xmlconfig.openInOrPlain(filename)[source]

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[source]

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.

Implementation

zope.schema.NativeStringLine

Read Only

False

Required

False

Default Value

None

Allowed Type

str

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

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)[source]

Include a zcml file

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

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)[source]

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)[source]

Execute a zcml file

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

Execute a zcml string

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

Bases: object

Provide high-level handling of configuration files.

See examples in tests/text_xmlconfig.py

zope.configuration.xmlconfig.testxmlconfig(file)[source]

xmlconfig that doesn’t raise configuration errors

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