z3c.baseregistry 1.0.0

Motivation

The current state of the component architecture allows us to

1. create a global components registry, populate it using ZCML, and use it via the zope.component API functions.

2. define local sites (local components registries), populate them with local (persistent) components, and use them selectively based on location – commonly defined by the path of the URL.

Unfortunately, it is impossible to populate local sites with ZCML. The main reason is the lack of addressibility of local sites during the initial startup process.

However, on the other hand we have a very advanced UI configuration system that involves views, resources, layers ans skins. So let’s compare the two.

1. Views/Resources in the UI are like registered components in the component architecture.

2. Skin Layers in the UI behave very much like registries. The default skin is like the global base registry. Skins, like local sites, are activated during traversal, but can be populated using ZCML.

3. Layers are really base layers to the skin layer. The equivalent in the component architecture is to specify bases for a components registry, which is possible since the Great Component Architecture refactoring for Zope 3.3 in 2006.

But layers can be defined and configured via ZCML. The purpose of this package is to be able to create base components registries and then populate them using ZCML. (As a side note: As skin layers and layers are practically the same components, there is no difference between the concept of global, local and base components registries.)

The second feature is specific to the Zope application server. It provides an UI to set the bases on a local site manager. The user can select among all registries that have been registered as IComponents utilities.

There are also a few options that could be considered in the future. For example, it would be simple to integrate the zope:registerIn directive (see below for documentation) into the zope:configure directive.

If the above text is too dry and theoretical for you, here is the summary. This package

1. implements Steve Alexander’s long dream (at least 3 years) of defining local sites via ZCML.

2. solves all of my (Stephan Richter) problems I am having with a complex Application Service Provider (ASP) setup.

3. implements a missing feature that you and everyone else really wanted, even if you did not know it yet.

Thanks goes to Jim Fulton, whose outstanding design of the zope.configuration and zope.component packages made the implementation of the feature such a breeze. I also want to thank Fred Drake for helping with the initial design ideas.

“Base Components” Registries

Base registries are global component registries implementing the IComponents interface. In comparison to the base global registry (also known as globalSiteManager), these registries are not necessarily available via module globals and must be registered with a parent registry, most commonly the base global registry:

>>> from z3c.baseregistry import baseregistry
>>> import zope.component
>>> myRegistry = baseregistry.BaseComponents(
...     zope.component.globalSiteManager, 'myRegistry')

>>> myRegistry
<BaseComponents myRegistry>

Since this registry does not implement any of the IComponents API itself, it is not necessary to demonstrate those features here. Please see the corresponding documentation in the zope.component package.

One feature of global registries must be that they pickle efficiently, since they can be referenced in persisted objects. As you can see, the base registry pickles quiet well:

>>> import cPickle
>>> jar = cPickle.dumps(myRegistry)
>>> len(jar)
100

However, when reading the jar, we get an error:

>>> cPickle.loads(jar)
Traceback (most recent call last):
...
ComponentLookupError: (<zope.component.interfaces.ComponentLookupError ...>,
                       <function BC at ...>,
                       (<BaseGlobalComponents base>, 'myRegistry'))

This is because we have not registered the registry in its parent as an IComponents utility, yet:

>>> from zope.component.interfaces import IComponents
>>> zope.component.provideUtility(myRegistry, IComponents, 'myRegistry')

>>> cPickle.loads(jar)
<BaseComponents myRegistry>

Thus it is very important that you always register your base registry with its parent!

Like any other components registry, a base registry can also have bases:

>>> myOtherRegistry = baseregistry.BaseComponents(
...     zope.component.globalSiteManager, 'myRegistry', (myRegistry,))
>>> myOtherRegistry.__bases__
(<BaseComponents myRegistry>,)

Let’s now have a look at how base registries can be defined and used via ZCML, which is the usual mode of operation.

Defining Base Registries

The above tasks are more commonly done in ZCML. Base components registries – or any IComponents implementation for that matter – can be seen as utilities providing the aformentioned interface and are distinguishable by name. So let’s define a “custom” registry:

>>> custom = baseregistry.BaseComponents(
...     zope.component.globalSiteManager, 'custom')

Let’s make sure that the parent of the custom registry is the base registry:

>>> custom.__parent__
<BaseGlobalComponents base>

The registry is then registered using the standard utility directive. After loading the meta directives for this package,

>>> from zope.configuration import xmlconfig
>>> context = xmlconfig.string('''
... <configure i18n_domain="zope">
...   <include package="z3c.baseregistry" file="meta.zcml" />
...   <include package="zope.component" file="meta.zcml" />
... </configure>
... ''')

we can register the registry:

>>> context = xmlconfig.string('''
... <configure xmlns="http://namespaces.zope.org/zope" i18n_domain="zope">
...
...   <utility
...       component="README.custom"
...       provides="zope.component.interfaces.IComponents"
...       name="custom" />
...
... </configure>
... ''', context=context)

The new registry can now be accessed as follows:

>>> custom = zope.component.getUtility(IComponents, name='custom')
>>> custom
<BaseComponents custom>

Populating Different Registries

Now to the interesting part. Let’s register components for both the global base and the “custom” registry. Let’s first create some utilities we can register:

>>> import zope.interface

>>> class IExample(zope.interface.Interface):
...     name = zope.interface.Attribute('Name of Example')

>>> class Example(object):
...     zope.interface.implements(IExample)
...     def __init__(self, name):
...         self.name = name
...     def __repr__(self):
...         return '<%s %r>' %(self.__class__.__name__, self.name)

>>> example1 = Example('example1')
>>> example2 = Example('example2')

Let’ now register “example1” in the global registry and “example2” in our custom registry:

>>> context = xmlconfig.string('''
... <configure xmlns="http://namespaces.zope.org/zope" i18n_domain="zope">
...
...   <utility component="README.example1"
...            name="example1" />
...
...   <registerIn registry="README.custom">
...     <utility component="README.example2"
...              name="example2" />
...   </registerIn>
...
... </configure>
... ''', context=context)

Let’s now make sure that the utilities have been registered in the right registry:

>>> zope.component.getUtility(IExample, name="example1")
<Example 'example1'>

>>> zope.component.getUtility(IExample, name="example2")
Traceback (most recent call last):
...
ComponentLookupError: (<InterfaceClass README.IExample>, 'example2')

>>> custom = zope.component.getUtility(IComponents, name='custom')

>>> custom.getUtility(IExample, name="example1")
Traceback (most recent call last):
...
ComponentLookupError: (<InterfaceClass README.IExample>, 'example1')

>>> custom.getUtility(IExample, name="example2")
<Example 'example2'>

Let’s now register other instances of the Example class without a name. This should not cause a conflict error:

>>> example3 = Example('example3')
>>> example4 = Example('example4')

>>> context = xmlconfig.string('''
... <configure xmlns="http://namespaces.zope.org/zope" i18n_domain="zope">
...
...   <utility component="README.example3" />
...
...   <registerIn registry="README.custom">
...     <utility component="README.example4" />
...   </registerIn>
...
... </configure>
... ''', context=context)

>>> zope.component.getUtility(IExample)
<Example 'example3'>

>>> custom.getUtility(IExample)
<Example 'example4'>

Using Base Registries

Most commonly base registries will be used in local site managers. So let’s create a local site:

>>> from zope.app.folder import Folder
>>> site = Folder()

>>> from zope.app.component.site import LocalSiteManager
>>> site.setSiteManager(LocalSiteManager(site))
>>> sm = site.getSiteManager()

Initially only the base global registry is a base of the local site manager:

>>> sm.__bases__
(<BaseGlobalComponents base>,)

Now only registrations from the base site are available:

>>> sm.getUtility(IExample)
<Example 'example3'>

>>> sm.getUtility(IExample, name="example1")
<Example 'example1'>

>>> sm.getUtility(IExample, name="example2")
Traceback (most recent call last):
...
ComponentLookupError: (<InterfaceClass README.IExample>, 'example2')

But if we add the “custom” registry, then things look more interesting:

>>> sm.__bases__ += (custom,)
>>> sm.__bases__
(<BaseGlobalComponents base>, <BaseComponents custom>)

>>> sm.getUtility(IExample)
<Example 'example3'>

>>> sm.getUtility(IExample, name="example1")
<Example 'example1'>

>>> sm.getUtility(IExample, name="example2")
<Example 'example2'>

But where is the registration for example 4? Well, the order of the bases matters, like the order of base classes in Python matters. The bases run from must specific to most generic. Thus, if we reverse the order,

>>> bases = list(sm.__bases__)
>>> bases.reverse()
>>> sm.__bases__ = bases
>>> sm.__bases__
(<BaseComponents custom>, <BaseGlobalComponents base>)

then our “custom” registry effectively overrides the global one:

>>> sm.getUtility(IExample)
<Example 'example4'>

>>> sm.getUtility(IExample, name="example1")
<Example 'example1'>

>>> sm.getUtility(IExample, name="example2")
<Example 'example2'>

Edge Cases and Food for Thought