zope.configuration.config

Configuration processor

class zope.configuration.config.ConfigurationContext[source]

Bases: object

Mix-in for implementing. zope.configuration.interfaces.IConfigurationContext.

Note that this class itself does not actually declare that it implements that interface; the subclass must do that. In addition, subclasses must provide a package attribute and a basepath attribute. If the base path is not None, relative paths are converted to absolute paths using the the base path. If the package is not none, relative imports are performed relative to the package.

In general, the basepath and package attributes should be consistent. When a package is provided, the base path should be set to the path of the package directory.

Subclasses also provide an actions attribute, which is a list of actions, an includepath attribute, and an info attribute.

The include path is appended to each action and is used when resolving conflicts among actions. Normally, only the a ConfigurationMachine provides the actions attribute. Decorators simply use the actions of the context they decorate. The includepath attribute is a tuple of names. Each name is typically the name of an included configuration file.

The info attribute contains descriptive information helpful when reporting errors. If not set, it defaults to an empty string.

The actions attribute is a sequence of dictionaries where each dictionary has the following keys:

  • discriminator, a value that identifies the action. Two actions that have the same (non None) discriminator conflict.
  • callable, an object that is called to execute the action,
  • args, positional arguments for the action
  • kw, keyword arguments for the action
  • includepath, a tuple of include file names (defaults to ())
  • info, an object that has descriptive information about the action (defaults to ‘’)
action(discriminator, callable=None, args=(), kw=None, order=0, includepath=None, info=None, **extra)[source]

Add an action with the given discriminator, callable and arguments.

For testing purposes, the callable and arguments may be omitted. In that case, a default noop callable is used.

The discriminator must be given, but it can be None, to indicate that the action never conflicts.

Examples:

>>> from zope.configuration.config import ConfigurationContext
>>> c = ConfigurationContext()

Normally, the context gets actions from subclasses. We’ll provide an actions attribute ourselves:

>>> c.actions = []

We’ll use a test callable that has a convenient string representation

>>> from zope.configuration.tests.directives import f
>>> c.action(1, f, (1, ), {'x': 1})
>>> from pprint import PrettyPrinter
>>> pprint = PrettyPrinter(width=60).pprint
>>> pprint(c.actions)
[{'args': (1,),
  'callable': f,
  'discriminator': 1,
  'includepath': (),
  'info': '',
  'kw': {'x': 1},
  'order': 0}]
>>> c.action(None)
>>> pprint(c.actions)
[{'args': (1,),
  'callable': f,
  'discriminator': 1,
  'includepath': (),
  'info': '',
  'kw': {'x': 1},
  'order': 0},
 {'args': (),
  'callable': None,
  'discriminator': None,
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0}]

Now set the include path and info:

>>> c.includepath = ('foo.zcml',)
>>> c.info = "?"
>>> c.action(None)
>>> pprint(c.actions[-1])
{'args': (),
 'callable': None,
 'discriminator': None,
 'includepath': ('foo.zcml',),
 'info': '?',
 'kw': {},
 'order': 0}

We can add an order argument to crudely control the order of execution:

>>> c.action(None, order=99999)
>>> pprint(c.actions[-1])
{'args': (),
 'callable': None,
 'discriminator': None,
 'includepath': ('foo.zcml',),
 'info': '?',
 'kw': {},
 'order': 99999}

We can also pass an includepath argument, which will be used as the the includepath for the action. (if includepath is None, self.includepath will be used):

>>> c.action(None, includepath=('abc',))
>>> pprint(c.actions[-1])
{'args': (),
 'callable': None,
 'discriminator': None,
 'includepath': ('abc',),
 'info': '?',
 'kw': {},
 'order': 0}

We can also pass an info argument, which will be used as the the source line info for the action. (if info is None, self.info will be used):

>>> c.action(None, info='abc')
>>> pprint(c.actions[-1])
{'args': (),
 'callable': None,
 'discriminator': None,
 'includepath': ('foo.zcml',),
 'info': 'abc',
 'kw': {},
 'order': 0}
checkDuplicate(filename)[source]

Check for duplicate imports of the same file.

Raises an exception if this file had been processed before. This is better than an unlimited number of conflict errors.

Examples:

>>> from zope.configuration.config import ConfigurationContext
>>> from zope.configuration.config import ConfigurationError
>>> c = ConfigurationContext()
>>> c.checkDuplicate('/foo.zcml')
>>> try:
...     c.checkDuplicate('/foo.zcml')
... except ConfigurationError as e:
...     # On Linux the exact msg has /foo, on Windows \foo.
...     str(e).endswith("foo.zcml' included more than once")
True

You may use different ways to refer to the same file:

>>> import zope.configuration
>>> c.package = zope.configuration
>>> import os
>>> d = os.path.dirname(zope.configuration.__file__)
>>> c.checkDuplicate('bar.zcml')
>>> try:
...   c.checkDuplicate(d + os.path.normpath('/bar.zcml'))
... except ConfigurationError as e:
...   str(e).endswith("bar.zcml' included more than once")
...
True
hasFeature(feature)[source]

Check whether a named feature has been provided.

Initially no features are provided.

Examples:

>>> from zope.configuration.config import ConfigurationContext
>>> c = ConfigurationContext()
>>> c.hasFeature('onlinehelp')
False

You can declare that a feature is provided

>>> c.provideFeature('onlinehelp')

and it becomes available

>>> c.hasFeature('onlinehelp')
True
path(filename)[source]

Compute package-relative paths.

Examples:

>>> import os
>>> from zope.configuration.config import ConfigurationContext
>>> c = ConfigurationContext()
>>> c.path("/x/y/z") == os.path.normpath("/x/y/z")
True
>>> c.path("y/z")
Traceback (most recent call last):
...
AttributeError: 'ConfigurationContext' object has no attribute 'package'
>>> import zope.configuration
>>> c.package = zope.configuration
>>> import os
>>> d = os.path.dirname(zope.configuration.__file__)
>>> c.path("y/z") == d + os.path.normpath("/y/z")
True
>>> c.path("y/./z") == d + os.path.normpath("/y/z")
True
>>> c.path("y/../z") == d + os.path.normpath("/z")
True
processFile(filename)[source]

Check whether a file needs to be processed.

Return True if processing is needed and False otherwise. If the file needs to be processed, it will be marked as processed, assuming that the caller will procces the file if it needs to be procssed.

Examples:

>>> from zope.configuration.config import ConfigurationContext
>>> c = ConfigurationContext()
>>> c.processFile('/foo.zcml')
True
>>> c.processFile('/foo.zcml')
False

You may use different ways to refer to the same file:

>>> import zope.configuration
>>> c.package = zope.configuration
>>> import os
>>> d = os.path.dirname(zope.configuration.__file__)
>>> c.processFile('bar.zcml')
True
>>> c.processFile(os.path.join(d, 'bar.zcml'))
False
provideFeature(feature)[source]

Declare that a named feature has been provided.

See hasFeature() for examples.

resolve(dottedname)[source]

Resolve a dotted name to an object.

Examples:

>>> from zope.configuration.config import ConfigurationContext
>>> c = ConfigurationContext()
>>> import zope, zope.interface
>>> c.resolve('zope') is zope
True
>>> c.resolve('zope.interface') is zope.interface
True
>>> c.resolve('zope.configuration.eek') #doctest: +NORMALIZE_WHITESPACE
Traceback (most recent call last):
...
ConfigurationError:
ImportError: Module zope.configuration has no global eek
>>> c.resolve('.config.ConfigurationContext')
Traceback (most recent call last):
...
AttributeError: 'ConfigurationContext' object has no attribute 'package'
>>> import zope.configuration
>>> c.package = zope.configuration
>>> c.resolve('.') is zope.configuration
True
>>> c.resolve('.config.ConfigurationContext') is ConfigurationContext
True
>>> c.resolve('..interface') is zope.interface
True
>>> c.resolve('str') is str
True
class zope.configuration.config.ConfigurationAdapterRegistry[source]

Bases: object

Simple adapter registry that manages directives as adapters.

Examples:

>>> from zope.configuration.interfaces import IConfigurationContext
>>> from zope.configuration.config import ConfigurationAdapterRegistry
>>> from zope.configuration.config import ConfigurationMachine
>>> r = ConfigurationAdapterRegistry()
>>> c = ConfigurationMachine()
>>> r.factory(c, ('http://www.zope.com', 'xxx'))
Traceback (most recent call last):
...
ConfigurationError: ('Unknown directive', 'http://www.zope.com', 'xxx')
>>> def f():
...     pass
>>> r.register(
...     IConfigurationContext, ('http://www.zope.com', 'xxx'), f)
>>> r.factory(c, ('http://www.zope.com', 'xxx')) is f
True
>>> r.factory(c, ('http://www.zope.com', 'yyy')) is f
Traceback (most recent call last):
...
ConfigurationError: ('Unknown directive', 'http://www.zope.com', 'yyy')
>>> r.register(IConfigurationContext, 'yyy', f)
>>> r.factory(c, ('http://www.zope.com', 'yyy')) is f
True

Test the documentation feature:

>>> from zope.configuration.config import IFullInfo
>>> r._docRegistry
[]
>>> r.document(('ns', 'dir'), IFullInfo, IConfigurationContext, None,
...            'inf', None)
>>> r._docRegistry[0][0] == ('ns', 'dir')
True
>>> r._docRegistry[0][1] is IFullInfo
True
>>> r._docRegistry[0][2] is IConfigurationContext
True
>>> r._docRegistry[0][3] is None
True
>>> r._docRegistry[0][4] == 'inf'
True
>>> r._docRegistry[0][5] is None
True
>>> r.document('all-dir', None, None, None, None)
>>> r._docRegistry[1][0]
('', 'all-dir')
class zope.configuration.config.ConfigurationMachine[source]

Bases: zope.configuration.config.ConfigurationAdapterRegistry, zope.configuration.config.ConfigurationContext

Configuration machine.

Example:

>>> from zope.configuration.config import ConfigurationMachine
>>> machine = ConfigurationMachine()
>>> ns = "http://www.zope.org/testing"

Register a directive:

>>> from zope.configuration.config import metans
>>> machine((metans, "directive"),
...         namespace=ns, name="simple",
...         schema="zope.configuration.tests.directives.ISimple",
...         handler="zope.configuration.tests.directives.simple")

and try it out:

>>> machine((ns, "simple"), a=u"aa", c=u"cc")
>>> from pprint import PrettyPrinter
>>> pprint = PrettyPrinter(width=60).pprint
>>> pprint(machine.actions)
[{'args': ('aa', 'xxx', 'cc'),
  'callable': f,
  'discriminator': ('simple', 'aa', 'xxx', 'cc'),
  'includepath': (),
  'info': None,
  'kw': {},
  'order': 0}]
execute_actions(clear=True, testing=False)[source]

Execute the configuration actions.

This calls the action callables after resolving conflicts.

For example:

>>> from zope.configuration.config import ConfigurationMachine
>>> output = []
>>> def f(*a, **k):
...    output.append(('f', a, k))
>>> context = ConfigurationMachine()
>>> context.actions = [
...   (1, f, (1,)),
...   (1, f, (11,), {}, ('x', )),
...   (2, f, (2,)),
...   ]
>>> context.execute_actions()
>>> output
[('f', (1,), {}), ('f', (2,), {})]

If the action raises an error, we convert it to a ConfigurationError.

>>> output = []
>>> def bad():
...    bad.xxx
>>> context.actions = [
...   (1, f, (1,)),
...   (1, f, (11,), {}, ('x', )),
...   (2, f, (2,)),
...   (3, bad, (), {}, (), 'oops')
...   ]
>>> context.execute_actions()
Traceback (most recent call last):
...
zope.configuration.config.ConfigurationExecutionError: oops
    AttributeError: 'function' object has no attribute 'xxx'

Note that actions executed before the error still have an effect:

>>> output
[('f', (1,), {}), ('f', (2,), {})]

If the exception was already a ConfigurationError, it is raised as-is with the action’s info added.

>>> def bad():
...     raise ConfigurationError("I'm bad")
>>> context.actions = [
...   (1, f, (1,)),
...   (1, f, (11,), {}, ('x', )),
...   (2, f, (2,)),
...   (3, bad, (), {}, (), 'oops')
...   ]
>>> context.execute_actions()
Traceback (most recent call last):
...
zope.configuration.exceptions.ConfigurationError: I'm bad
    oops
pass_through_exceptions = ()

These Exception subclasses are allowed to be raised from execute_actions without being re-wrapped into a ConfigurationError. (BaseException and other ConfigurationError instances are never wrapped.)

Users of instances of this class may modify this before calling execute_actions if they need to propagate specific exceptions.

New in version 4.2.0.

interface zope.configuration.config.IStackItem[source]

Configuration machine stack items

Stack items are created when a directive is being processed.

A stack item is created for each directive use.

contained(name, data, info)

Begin processing a contained directive

The data are a dictionary of attribute names mapped to unicode strings.

The info argument is an object that can be converted to a string and that contains information about the directive.

The begin method returns the next item to be placed on the stack.

finish()

Finish processing a directive

class zope.configuration.config.SimpleStackItem(context, handler, info, *argdata)[source]

Bases: object

Simple stack item

A simple stack item can’t have anything added after it. It can only be removed. It is used for simple directives and subdirectives, which can’t contain other directives.

It also defers any computation until the end of the directive has been reached.

class zope.configuration.config.RootStackItem(context)[source]

Bases: object

A root stack item.

contained(name, data, info)[source]

Handle a contained directive

We have to compute a new stack item by getting a named adapter for the current context object.

class zope.configuration.config.GroupingStackItem(context)[source]

Bases: zope.configuration.config.RootStackItem

Stack item for a grouping directive

A grouping stack item is in the stack when a grouping directive is being processed. Grouping directives group other directives. Often, they just manage common data, but they may also take actions, either before or after contained directives are executed.

A grouping stack item is created with a grouping directive definition, a configuration context, and directive data.

To see how this works, let’s look at an example:

We need a context. We’ll just use a configuration machine

>>> from zope.configuration.config import GroupingStackItem
>>> from zope.configuration.config import ConfigurationMachine
>>> context = ConfigurationMachine()

We need a callable to use in configuration actions. We’ll use a convenient one from the tests:

>>> from zope.configuration.tests.directives import f

We need a handler for the grouping directive. This is a class that implements a context decorator. The decorator must also provide before and after methods that are called before and after any contained directives are processed. We’ll typically subclass GroupingContextDecorator, which provides context decoration, and default before and after methods.

>>> from zope.configuration.config import GroupingContextDecorator
>>> class SampleGrouping(GroupingContextDecorator):
...    def before(self):
...       self.action(('before', self.x, self.y), f)
...    def after(self):
...       self.action(('after'), f)

We’ll use our decorator to decorate our initial context, providing keyword arguments x and y:

>>> dec = SampleGrouping(context, x=1, y=2)

Note that the keyword arguments are made attributes of the decorator.

Now we’ll create the stack item.

>>> item = GroupingStackItem(dec)

We still haven’t called the before action yet, which we can verify by looking at the context actions:

>>> context.actions
[]

Subdirectives will get looked up as adapters of the context.

We’ll create a simple handler:

>>> def simple(context, data, info):
...     context.action(("simple", context.x, context.y, data), f)
...     return info

and register it with the context:

>>> from zope.configuration.interfaces import IConfigurationContext
>>> from zope.configuration.config import testns
>>> context.register(IConfigurationContext, (testns, 'simple'), simple)

This handler isn’t really a propert handler, because it doesn’t return a new context. It will do for this example.

Now we’ll call the contained method on the stack item:

>>> item.contained((testns, 'simple'), {'z': 'zope'}, "someinfo")
'someinfo'

We can verify thet the simple method was called by looking at the context actions. Note that the before method was called before handling the contained directive.

>>> from pprint import PrettyPrinter
>>> pprint = PrettyPrinter(width=60).pprint
>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': ('before', 1, 2),
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0},
 {'args': (),
  'callable': f,
  'discriminator': ('simple', 1, 2, {'z': 'zope'}),
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0}]

Finally, we call finish, which calls the decorator after method:

>>> item.finish()
>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': ('before', 1, 2),
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0},
 {'args': (),
  'callable': f,
  'discriminator': ('simple', 1, 2, {'z': 'zope'}),
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0},
 {'args': (),
  'callable': f,
  'discriminator': 'after',
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0}]

If there were no nested directives:

>>> context = ConfigurationMachine()
>>> dec = SampleGrouping(context, x=1, y=2)
>>> item = GroupingStackItem(dec)
>>> item.finish()

Then before will be when we call finish:

>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': ('before', 1, 2),
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0},
 {'args': (),
  'callable': f,
  'discriminator': 'after',
  'includepath': (),
  'info': '',
  'kw': {},
  'order': 0}]
contained(name, data, info)[source]

Handle a contained directive

We have to compute a new stack item by getting a named adapter for the current context object.

class zope.configuration.config.ComplexStackItem(meta, context, data, info)[source]

Bases: object

Complex stack item

A complex stack item is in the stack when a complex directive is being processed. It only allows subdirectives to be used.

A complex stack item is created with a complex directive definition (IComplexDirectiveContext), a configuration context, and directive data.

To see how this works, let’s look at an example:

We need a context. We’ll just use a configuration machine

>>> from zope.configuration.config import ConfigurationMachine
>>> context = ConfigurationMachine()

We need a callable to use in configuration actions. We’ll use a convenient one from the tests:

>>> from zope.configuration.tests.directives import f

We need a handler for the complex directive. This is a class with a method for each subdirective:

>>> class Handler(object):
...   def __init__(self, context, x, y):
...      self.context, self.x, self.y = context, x, y
...      context.action('init', f)
...   def sub(self, context, a, b):
...      context.action(('sub', a, b), f)
...   def __call__(self):
...      self.context.action(('call', self.x, self.y), f)

We need a complex directive definition:

>>> from zope.interface import Interface
>>> from zope.schema import TextLine
>>> from zope.configuration.config import ComplexDirectiveDefinition
>>> class Ixy(Interface):
...    x = TextLine()
...    y = TextLine()
>>> definition = ComplexDirectiveDefinition(
...        context, name="test", schema=Ixy,
...        handler=Handler)
>>> class Iab(Interface):
...    a = TextLine()
...    b = TextLine()
>>> definition['sub'] = Iab, ''

OK, now that we have the context, handler and definition, we’re ready to use a stack item.

>>> from zope.configuration.config import ComplexStackItem
>>> item = ComplexStackItem(
...     definition, context, {'x': u'xv', 'y': u'yv'}, 'foo')

When we created the definition, the handler (factory) was called.

>>> from pprint import PrettyPrinter
>>> pprint = PrettyPrinter(width=60).pprint
>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': 'init',
  'includepath': (),
  'info': 'foo',
  'kw': {},
  'order': 0}]

If a subdirective is provided, the contained method of the stack item is called. It will lookup the subdirective schema and call the corresponding method on the handler instance:

>>> simple = item.contained(('somenamespace', 'sub'),
...                         {'a': u'av', 'b': u'bv'}, 'baz')
>>> simple.finish()

Note that the name passed to contained is a 2-part name, consisting of a namespace and a name within the namespace.

>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': 'init',
  'includepath': (),
  'info': 'foo',
  'kw': {},
  'order': 0},
 {'args': (),
  'callable': f,
  'discriminator': ('sub', 'av', 'bv'),
  'includepath': (),
  'info': 'baz',
  'kw': {},
  'order': 0}]

The new stack item returned by contained is one that doesn’t allow any more subdirectives,

When all of the subdirectives have been provided, the finish method is called:

>>> item.finish()

The stack item will call the handler if it is callable.

>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': 'init',
  'includepath': (),
  'info': 'foo',
  'kw': {},
  'order': 0},
 {'args': (),
  'callable': f,
  'discriminator': ('sub', 'av', 'bv'),
  'includepath': (),
  'info': 'baz',
  'kw': {},
  'order': 0},
 {'args': (),
  'callable': f,
  'discriminator': ('call', 'xv', 'yv'),
  'includepath': (),
  'info': 'foo',
  'kw': {},
  'order': 0}]
contained(name, data, info)[source]

Handle a subdirective

class zope.configuration.config.GroupingContextDecorator(context, **kw)[source]

Bases: zope.configuration.config.ConfigurationContext

Helper mix-in class for building grouping directives

See the discussion (and test) in GroupingStackItem.

class zope.configuration.config.DirectiveSchema(**kw)[source]

Bases: zope.configuration.fields.GlobalInterface

A field that contains a global variable value that must be a schema

interface zope.configuration.config.IDirectivesInfo[source]

Schema for the directives directive

namespace

Namespace

The namespace in which directives’ names will be defined

Implementation:zope.schema.URI
Read Only:False
Required:True
Default Value:None
Allowed Type:str
class zope.configuration.config.DirectivesHandler(context, **kw)[source]

Bases: zope.configuration.config.GroupingContextDecorator

Handler for the directives directive

This is just a grouping directive that adds a namespace attribute to the normal directive context.

interface zope.configuration.config.IDirectiveInfo[source]

Information common to all directive definitions.

name

Directive name

The name of the directive being defined

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:unicode
schema

Directive handler

The dotted name of the directive handler

Implementation:zope.configuration.config.DirectiveSchema
Read Only:False
Required:True
Default Value:None

Value Type

Implementation:zope.schema.InterfaceField
Read Only:False
Required:True
Default Value:None
interface zope.configuration.config.IFullInfo[source]

Extends: zope.configuration.config.IDirectiveInfo

Information that all top-level directives (not subdirectives) have.

handler

Directive handler

The dotted name of the directive handler

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

The directive types the directive can be used in

The interface of the directives that can contain the directive

Implementation:zope.configuration.fields.GlobalInterface
Read Only:False
Required:True
Default Value:<InterfaceClass zope.configuration.interfaces.IConfigurationContext>

Value Type

Implementation:zope.schema.InterfaceField
Read Only:False
Required:True
Default Value:None
interface zope.configuration.config.IStandaloneDirectiveInfo[source]

Extends: zope.configuration.config.IDirectivesInfo, zope.configuration.config.IFullInfo

Info for full directives defined outside a directives directives

zope.configuration.config.defineSimpleDirective(context, name, schema, handler, namespace='', usedIn=<InterfaceClass zope.configuration.interfaces.IConfigurationContext>)[source]

Define a simple directive

Define and register a factory that invokes the simple directive and returns a new stack item, which is always the same simple stack item.

If the namespace is ‘*’, the directive is registered for all namespaces.

Example:

>>> from zope.configuration.config import ConfigurationMachine
>>> context = ConfigurationMachine()
>>> from zope.interface import Interface
>>> from zope.schema import TextLine
>>> from zope.configuration.tests.directives import f
>>> class Ixy(Interface):
...    x = TextLine()
...    y = TextLine()
>>> def s(context, x, y):
...    context.action(('s', x, y), f)
>>> from zope.configuration.config import defineSimpleDirective
>>> defineSimpleDirective(context, 's', Ixy, s, testns)
>>> context((testns, "s"), x=u"vx", y=u"vy")
>>> from pprint import PrettyPrinter
>>> pprint = PrettyPrinter(width=60).pprint
>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': ('s', 'vx', 'vy'),
  'includepath': (),
  'info': None,
  'kw': {},
  'order': 0}]
>>> context(('http://www.zope.com/t1', "s"), x=u"vx", y=u"vy")
Traceback (most recent call last):
...
ConfigurationError: ('Unknown directive', 'http://www.zope.com/t1', 's')
>>> context = ConfigurationMachine()
>>> defineSimpleDirective(context, 's', Ixy, s, "*")
>>> context(('http://www.zope.com/t1', "s"), x=u"vx", y=u"vy")
>>> pprint(context.actions)
[{'args': (),
  'callable': f,
  'discriminator': ('s', 'vx', 'vy'),
  'includepath': (),
  'info': None,
  'kw': {},
  'order': 0}]
zope.configuration.config.defineGroupingDirective(context, name, schema, handler, namespace='', usedIn=<InterfaceClass zope.configuration.interfaces.IConfigurationContext>)[source]

Define a grouping directive

Define and register a factory that sets up a grouping directive.

If the namespace is ‘*’, the directive is registered for all namespaces.

Example:

>>> from zope.configuration.config import ConfigurationMachine
>>> context = ConfigurationMachine()
>>> from zope.interface import Interface
>>> from zope.schema import TextLine
>>> class Ixy(Interface):
...    x = TextLine()
...    y = TextLine()

We won’t bother creating a special grouping directive class. We’ll just use GroupingContextDecorator, which simply sets up a grouping context that has extra attributes defined by a schema:

>>> from zope.configuration.config import defineGroupingDirective
>>> from zope.configuration.config import GroupingContextDecorator
>>> defineGroupingDirective(context, 'g', Ixy,
...                         GroupingContextDecorator, testns)
>>> context.begin((testns, "g"), x=u"vx", y=u"vy")
>>> context.stack[-1].context.x
'vx'
>>> context.stack[-1].context.y
'vy'
>>> context(('http://www.zope.com/t1', "g"), x=u"vx", y=u"vy")
Traceback (most recent call last):
...
ConfigurationError: ('Unknown directive', 'http://www.zope.com/t1', 'g')
>>> context = ConfigurationMachine()
>>> defineGroupingDirective(context, 'g', Ixy,
...                         GroupingContextDecorator, "*")
>>> context.begin(('http://www.zope.com/t1', "g"), x=u"vx", y=u"vy")
>>> context.stack[-1].context.x
'vx'
>>> context.stack[-1].context.y
'vy'
class zope.configuration.config.ComplexDirectiveDefinition(context, **kw)[source]

Bases: zope.configuration.config.GroupingContextDecorator, dict

Handler for defining complex directives

See the description and tests for ComplexStackItem.

interface zope.configuration.config.IProvidesDirectiveInfo[source]

Information for a <meta:provides> directive

feature

Feature name

The name of the feature being provided

You can test available features with zcml:condition=”have featurename”.

Implementation:zope.schema.TextLine
Read Only:False
Required:True
Default Value:None
Allowed Type:unicode
zope.configuration.config.provides(context, feature)[source]

Declare that a feature is provided in context.

Example:

>>> from zope.configuration.config import ConfigurationContext
>>> from zope.configuration.config import provides
>>> c = ConfigurationContext()
>>> provides(c, 'apidoc')
>>> c.hasFeature('apidoc')
True

Spaces are not allowed in feature names (this is reserved for providing many features with a single directive in the future).

>>> provides(c, 'apidoc onlinehelp')
Traceback (most recent call last):
  ...
ValueError: Only one feature name allowed
>>> c.hasFeature('apidoc onlinehelp')
False
zope.configuration.config.toargs(context, schema, data)[source]

Marshal data to an argument dictionary using a schema

Names that are python keywords have an underscore added as a suffix in the schema and in the argument list, but are used without the underscore in the data.

The fields in the schema must all implement IFromUnicode.

All of the items in the data must have corresponding fields in the schema unless the schema has a true tagged value named ‘keyword_arguments’.

Example:

>>> from zope.configuration.config import toargs
>>> from zope.schema import BytesLine
>>> from zope.schema import Float
>>> from zope.schema import Int
>>> from zope.schema import TextLine
>>> from zope.schema import URI
>>> class schema(Interface):
...     in_ = Int(constraint=lambda v: v > 0)
...     f = Float()
...     n = TextLine(min_length=1, default=u"rob")
...     x = BytesLine(required=False)
...     u = URI()
>>> context = ConfigurationMachine()
>>> from pprint import PrettyPrinter
>>> pprint = PrettyPrinter(width=50).pprint
>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org' }))
{'f': 1.2,
 'in_': 1,
 'n': 'bob',
 'u': 'http://www.zope.org',
 'x': b'x.y.z'}

If we have extra data, we’ll get an error:

>>> toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org', 'a': u'1'})
Traceback (most recent call last):
...
ConfigurationError: ('Unrecognized parameters:', 'a')

Unless we set a tagged value to say that extra arguments are ok:

>>> schema.setTaggedValue('keyword_arguments', True)
>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org', 'a': u'1'}))
{'a': '1',
 'f': 1.2,
 'in_': 1,
 'n': 'bob',
 'u': 'http://www.zope.org',
 'x': b'x.y.z'}

If we omit required data we get an error telling us what was omitted:

>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z'}))
Traceback (most recent call last):
...
ConfigurationError: ('Missing parameter:', 'u')

Although we can omit not-required data:

>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob',
...          'u': u'http://www.zope.org', 'a': u'1'}))
{'a': '1',
 'f': 1.2,
 'in_': 1,
 'n': 'bob',
 'u': 'http://www.zope.org'}

And we can omit required fields if they have valid defaults (defaults that are valid values):

>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2',
...          'u': u'http://www.zope.org', 'a': u'1'}))
{'a': '1',
 'f': 1.2,
 'in_': 1,
 'n': 'rob',
 'u': 'http://www.zope.org'}

We also get an error if any data was invalid:

>>> pprint(toargs(context, schema,
...        {'in': u'0', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org', 'a': u'1'}))
Traceback (most recent call last):
...
ConfigurationError: ('Invalid value for', 'in', '0')
zope.configuration.config.resolveConflicts(actions)[source]

Resolve conflicting actions.

Given an actions list, identify and try to resolve conflicting actions. Actions conflict if they have the same non-None discriminator. Conflicting actions can be resolved if the include path of one of the actions is a prefix of the includepaths of the other conflicting actions and is unequal to the include paths in the other conflicting actions.

exception zope.configuration.config.ConfigurationConflictError(conflicts)[source]

Bases: zope.configuration.exceptions.ConfigurationError