z3c.configurator 1.3.0

Dependencies

Now that we have simple configuration plugins, we can also develop plugins that depend on another one. Let’s create a configuration plugin that adds some additional data to the foo attribute. Clearly, the foo attribute has to exist before this step can be taken. The dependencies attribute can be used to specify all plugin dependencies by name:

>>> class ExtendFooAttribute(configurator.ConfigurationPluginBase):
...     zope.component.adapts(ISomething)
...     dependencies = ('add foo',)
...
...     def __call__(self, data):
...         self.context.foo = u'Text: ' + self.context.foo

>>> zope.component.provideAdapter(ExtendFooAttribute, name='extend foo')

If we now execute the configuration again, the extended result should be seen:

>>> something = Something()
>>> configurator.configure(something, {'foo': u'my value'})
>>> something.foo
u'Text: my value'

Data Schemas

For purely informational purposes, a schema attribute is used on the plugin to describe the fields that the plugin expects from the data dictionary. For adding another simple attribute, this could look as follows:

>>> import zope.schema
>>> class IAddBar(zope.interface.Interface):
...     bar = zope.schema.Text(title=u'Bar')

>>> class AddBarAttribute(configurator.SchemaConfigurationPluginBase):
...     zope.component.adapts(ISomething)
...     schema = IAddBar
...
...     def __call__(self, data):
...         self.verify(data)
...         setattr(self.context, 'bar', data.get('bar'))

>>> zope.component.provideAdapter(AddBarAttribute, name='add bar')

The advantage of using the base class for this case is that it provides a verify() method that allows you to verify the data against the shema. We can now run the configuration again:

>>> something = Something()
>>> configurator.configure(something, {'foo': u'my value', 'bar': u'value'})
>>> something.bar
u'value'

The value must exist and be valid:

>>> something = Something()
>>> configurator.configure(something, {'foo': u'my value'})
Traceback (most recent call last):
...
RequiredMissing: bar

>>> something = Something()
>>> configurator.configure(something, {'foo': u'my value', 'bar': 1})
Traceback (most recent call last):
...
WrongType: (1, <type 'unicode'>, 'bar')

Data Namespaces

In order to not confuse attribute names if two plugins share a common name it is possible to pass data as a dictionary of dictionaries. The keys of the dictionary is the name under which the plugins are registered.

>>> something = Something()
>>> data = {u'add foo': {'foo': u'foo value'},
...         u'add bar': {'bar': u'bar value'}}
>>> configurator.configure(something, data, useNameSpaces=True)
>>> something.foo, something.bar
(u'Text: foo value', u'bar value')

Named Configuration

Sometimes we do not want all registered configuration plugins to be executed. This can be achieved by providing the names argument to the configure function.

Let us create a new something:

>>> something = Something()

If we now configure it without names we get both attributes set.

>>> configurator.configure(something, {'foo': u'my value', 'bar': u'asdf'})
>>> something.__dict__
{'foo': u'Text: my value', 'bar': u'asdf'}

Now let us just configure the plugin ‘add bar’.

>>> something = Something()
>>> configurator.configure(something, {'foo': u'my value', 'bar': u'asdf'},
...     names=['add bar'])
>>> something.__dict__
{'bar': u'asdf'}

Dependencies of plugins are always executed - they don’t have to be added to the `names` argument.

>>> something = Something()
>>> configurator.configure(something, {'foo': u'my value'},
...     names=['extend foo'])
>>> something.foo
u'Text: my value'

Named configurations are usefull when called manually through the web (see browser/README.txt). The configurator package does not look if a configuration is already applied if called twice. It is the responsibility of the plugin to be aware that it doesn’t do things twice or delete things.

Wrong Implementations

A configurator must provide a __call__ method.

>>> class CallNotImplemented(configurator.ConfigurationPluginBase):
...     zope.component.adapts(ISomething)
>>> zope.component.provideAdapter(CallNotImplemented, name='no call')

>>> configurator.configure(something, None,  names=['no call'])
Traceback (most recent call last):
...
NotImplementedError

The same must happen for a schema base configurator.

>>> class SchemaCallNotImplemented(configurator.SchemaConfigurationPluginBase):
...     zope.component.adapts(ISomething)
>>> zope.component.provideAdapter(SchemaCallNotImplemented, name='schema no call')

>>> configurator.configure(something, None,  names=['schema no call'])
Traceback (most recent call last):
...
NotImplementedError

No Recursion

It’s possible to define recursive dependencies without to run into recursion errors. Let’s define a new plugin free object:

>>> class IFoo(zope.interface.Interface):
...     """Just a foo interface."""

>>> class Foo(object):
...     """Implementation of foo."""
...     zope.interface.implements(IFoo)

Let’s define another plugin named first which depends on a plugin named second.

>>> class FirstPlugin(configurator.ConfigurationPluginBase):
...     zope.component.adapts(IFoo)
...     dependencies = ('second',)
...
...     def __call__(self, data):
...         print 'FirstPlugin called'

>>> zope.component.provideAdapter(FirstPlugin, name='first')

And define a plugin named second which depends on first:

>>> class SecondPlugin(configurator.ConfigurationPluginBase):
...     zope.component.adapts(IFoo)
...     dependencies = ('first',)
...
...     def __call__(self, data):
...         print 'SecondPlugin called'

>>> zope.component.provideAdapter(SecondPlugin, name='second')

>>> foo = Foo()
>>> configurator.configure(foo, {})
FirstPlugin called
SecondPlugin called

1.3.0 (2010-12-12)

• Updated test set up to run with ZTK 1.0.

Version 1.2.1 (2009-12-27)

• Moved browser dependencies to ‘zmi’ extras

Version 1.2.0 (2009-12-19)

• Made registration of browser views conditional

• Move packages required for testing to ‘test’ extras

• Remove old zpkg-related SETUP.cfg file.

• Copyright “Zope Foundation and Contributors”

Version 1.1.2 (2009-01-04)

• Added possibility to apply only specific named plugins in configure.

• New option to configure allows to have namespaced data to resolve naming conflicts.

• Added a page to call configurators TTW. This is the first step towards mergin z3c.configurator and z3c.sampledata into one package.

• Added documentation to Pypi home page.

• bugfix: Defining recursive dependent names in IConfigurationPlugin dependencies, ends in recursive plugin lookup.

• bugfix: SchemaConfigurationPluginBase now implements ISchemaConfigurationPluginBase.

Version 1.1.1 (unknown)

• Initial Release