Type ComplexStackItem

object --+
         |
        ComplexStackItem

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 us 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

>>> 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:

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

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

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

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

>>> context.actions
[('init', f, (), {}, (), 'foo')]

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.

>>> from pprint import PrettyPrinter
>>> pprint=PrettyPrinter(width=60).pprint

>>> pprint(context.actions)
[('init', f, (), {}, (), 'foo'),
 (('sub', u'av', u'bv'), f, (), {}, (), 'baz')]

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)
[('init', f, (), {}, (), 'foo'),
 (('sub', u'av', u'bv'), f, (), {}, (), 'baz'),
 (('call', u'xv', u'yv'), f, (), {}, (), 'foo')]