zope.configuration.xmlconfig — zope.configuration 4.0 documentation

### Navigation

- index
- modules |
- next |
- previous |
- zope.configuration 4.0 documentation »
- `zope.configuration` API Reference »

# `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/text_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.

### Navigation

- index
- modules |
- next |
- previous |
- zope.configuration 4.0 documentation »
- `zope.configuration` API Reference »