plone.registry 1.0b1

Changelog

Simple records

Let’s now create a record. A record must have a name. This should be a dotted name, and contain ASCII characters only. By convention, it should be all lowercase and start with the name of the package that defines the record.

It is also possible to create a number of records based on a single schema interface - see below - but for now, we will focus on simple records.

Before we can create the record, we must create the field that describes it. Fields are based on the venerable zope.schema package, but plone.registry only supports certain fields, and disallows use of a few properties even of those. As a rule of thumb, so long as a field stores a Python primitive, it is supported; the same goes for attributes of fields.

Thus:

• Fields like Object, InterfaceField and so on are not supported

• A custom constraint method is not supported.

• The order attribute will always be set to -1

• For Choice fields, only named vocabularies are supported: you cannot reference a particular source or source binder

• The key_type and value_type properties of Dict, List, Tuple, Set and Frozenset may only contain persistent fields.

See field.text for more details.

Creating records from interfaces

As an application developer, it is often desirable to define settings as traditional interfaces with zope.schema fields. plone.registry includes support for creating a set of records from a single interface.

To test this, we have created an interface, IMailSettings, with two fields, sender and smtp_host.

>>> from plone.registry.tests import IMailSettings

Note that this contains standard fields.

>>> IMailSettings['sender']
<zope.schema._bootstrapfields.TextLine object at ...>

>>> IMailSettings['smtp_host']
<zope.schema._field.URI object at ...>

We can create records from this interface like this:

>>> registry.registerInterface(IMailSettings)

One record for each field in the interface has now been created. Their names are the full dotted names to those fields:

>>> sender_record = registry.records['plone.registry.tests.IMailSettings.sender']
>>> smtp_host_record = registry.records['plone.registry.tests.IMailSettings.smtp_host']

The fields used in the records will be the equivalent persistent versions of the fields from the original interface.

>>> sender_record.field
<plone.registry.field.TextLine object at ...>

>>> smtp_host_record.field
<plone.registry.field.URI object at ...>

This feat is accomplished internally by adapting the field to the IPersistentField interface. There is a default adapter factory that works for all fields defined in plone.registry.field. You can of course define your own adapter if you have a custom field type, but bear in mind the golden rules of any persistent field:

• The field must store only primitives or other persistent fields

• It must not reference a function, class, interface or other method that could break if a package is uninstalled.

If we have a field for which there is no IPersistentField adapter, we will get an error:

>>> from plone.registry.tests import IMailPreferences
>>> IMailPreferences['settings']
<zope.schema._field.Object object at ...>

>>> registry.registerInterface(IMailPreferences)
Traceback (most recent call last):
...
TypeError: There is no persistent field equivalent for the field `settings` of type `Object`.

Whoops! We can, however, tell registerInterface() to ignore one or more fields.

>>> registry.registerInterface(IMailPreferences, omit=('settings',))

Once an interface’s records have been registered, we can get and set their values as normal:

>>> registry['plone.registry.tests.IMailSettings.sender']
u'root@localhost'

>>> registry['plone.registry.tests.IMailSettings.sender'] = u"webmaster@localhost"
>>> registry['plone.registry.tests.IMailSettings.sender']
u'webmaster@localhost'

If we sub-sequently re-register the same interface, the value will be retained if possible:

>>> registry.registerInterface(IMailSettings)
>>> registry['plone.registry.tests.IMailSettings.sender']
u'webmaster@localhost'

However, if the value is no longer valid, we will revert to the default. To test that, let’s sneakily modify the field for a while.

>>> old_field = IMailSettings['sender']
>>> IMailSettings._InterfaceClass__attrs['sender'] = field.Int(title=u"Definitely not a string", default=2)
>>> if hasattr(IMailSettings, '_v_attrs'):
...     del IMailSettings._v_attrs['sender']
>>> registry.registerInterface(IMailSettings)
>>> registry['plone.registry.tests.IMailSettings.sender']
2

But let’s put it back the way it was.

>>> IMailSettings._InterfaceClass__attrs['sender'] = old_field
>>> if hasattr(IMailSettings, '_v_attrs'):
...     del IMailSettings._v_attrs['sender']
>>> registry.registerInterface(IMailSettings)
>>> registry['plone.registry.tests.IMailSettings.sender']
u'root@localhost'

IObjectEvent-style redispatchers

There is a special event handler which takes care of re-dispatching registry events based on the schema interface prescribed by the record.

Let’s re-set the event testing framework and register the re-dispatching event subscriber. Normally, this would happen automatically by including this package’s ZCML.

>>> from zope.component.eventtesting import clearEvents
>>> from zope.component import provideHandler
>>> from plone.registry.events import redispatchInterfaceAwareRecordEvents
>>> clearEvents()
>>> provideHandler(redispatchInterfaceAwareRecordEvents)

We’ll then register a schema interface.

>>> from plone.registry.tests import IMailSettings
>>> registry.registerInterface(IMailSettings)

We could now register an event handler to print any record event occurring on an IMailSettings record. More specialised event handlers for e.g. IRecordModifiedEvent or IRecordRemovedEvent are of course also possible. Note that it is not possible to re-dispatch IRecordAddedEvents, so these are never caught.

>>> from zope.component import adapter
>>> @adapter(IMailSettings, IRecordEvent)
... def print_mail_settings_events(proxy, event):
...     print "Got", event, "for", proxy
>>> provideHandler(print_mail_settings_events)

Let’s now modify one of the records for this interface. The event handler should react immediately.

>>> registry['plone.registry.tests.IMailSettings.sender'] = u"Some sender"
Got <RecordModifiedEvent for plone.registry.tests.IMailSettings.sender> for <RecordsProxy for plone.registry.tests.IMailSettings>

Let’s also modify a non-interface-aware record, for comparison’s sake. Here, there is nothing printed.

>>> registry['plone.registry.tests.age'] = 3

We can try a record-removed event as well:

>>> del registry.records['plone.registry.tests.IMailSettings.sender']
Got <RecordRemovedEvent for plone.registry.tests.IMailSettings.sender> for <RecordsProxy for plone.registry.tests.IMailSettings>

The basic events that have been dispatched are:

>>> getEvents(IRecordEvent)
[<RecordAddedEvent for plone.registry.tests.IMailSettings.sender>,
 <RecordAddedEvent for plone.registry.tests.IMailSettings.smtp_host>,
 <RecordModifiedEvent for plone.registry.tests.IMailSettings.sender>,
 <RecordModifiedEvent for plone.registry.tests.age>,
 <RecordRemovedEvent for plone.registry.tests.IMailSettings.sender>]