Type GroupingStackItem

   object --+    
            |    
RootStackItem --+
                |
               GroupingStackItem

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

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

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

>>> 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)
[(('before', 1, 2), f),
 (('simple', 1, 2, {'z': 'zope'}), f)]

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

>>> item.finish()

>>> pprint(context.actions)
[(('before', 1, 2), f),
 (('simple', 1, 2, {'z': 'zope'}), f),
 ('after', f)]

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)
[(('before', 1, 2), f), ('after', f)]