Class
zope.app.component.vocabulary.UtilityVocabulary

Vocabulary that provides utilities of a specified interface.

Here is a short example of how the vocabulary should work.

First we need to create a utility interface and some utilities:

>>> class IObject(Interface):
...     'Simple interface to mark object utilities.'
>>>
>>> class Object(object):
...     implements(IObject)
...     def __init__(self, name):
...         self.name = name
...     def __repr__(self):
...         return '<Object %s>' %self.name

Now we register some utilities for IObject

>>> from zope.app.testing import ztapi
>>> object1 = Object('object1')
>>> ztapi.provideUtility(IObject, object1, 'object1')
>>> object2 = Object('object2')
>>> ztapi.provideUtility(IObject, object2, 'object2')
>>> object3 = Object('object3')
>>> ztapi.provideUtility(IObject, object3, 'object3')
>>> object4 = Object('object4')

We are now ready to create a vocabulary that we can use; in our case everything is global, so the context is None.

>>> vocab = UtilityVocabulary(None, interface=IObject)
>>> import pprint
>>> pprint.pprint(vocab._terms.items())
[(u'object1', <UtilityTerm object1, instance of Object>),
 (u'object2', <UtilityTerm object2, instance of Object>),
 (u'object3', <UtilityTerm object3, instance of Object>)]

Now let's see how the other methods behave in this context. First we can just use the 'in' opreator to test whether a value is available.

>>> object1 in vocab
True
>>> object4 in vocab
False

We can also create a lazy iterator. Note that the utility terms might appear in a different order than the utilities were registered.

>>> iterator = iter(vocab)
>>> terms = list(iterator)
>>> names = [term.token for term in terms]
>>> names.sort()
>>> names
[u'object1', u'object2', u'object3']

Determining the amount of utilities available via the vocabulary is also possible.

>>> len(vocab)
3

Next we are looking at some of the more vocabulary-characteristic API methods.

One can get a term for a given value using getTerm():

>>> vocab.getTerm(object1)
<UtilityTerm object1, instance of Object>
>>> vocab.getTerm(object4)
Traceback (most recent call last):
...
LookupError: <Object object4>

On the other hand, if you want to get a term by the token, then you do that with:

>>> vocab.getTermByToken('object1')
<UtilityTerm object1, instance of Object>
>>> vocab.getTermByToken('object4')
Traceback (most recent call last):
...
LookupError: object4

That's it. It is all pretty straight forward, but it allows us to easily create a vocabulary for any utility. In fact, to make it easy to register such a vocabulary via ZCML, the interface argument to the constructor can be a string that is resolved via the utility registry. The ZCML looks like this:

<zope:vocabulary
name='IObjects' factory='zope.app.utility.vocabulary.UtilityVocabulary' interface='zope.app.utility.vocabulary.IObject' />
>>> ztapi.provideUtility(IInterface, IObject,
...                      'zope.app.utility.vocabulary.IObject')
>>> vocab = UtilityVocabulary(
...     None, interface='zope.app.utility.vocabulary.IObject')
>>> pprint.pprint(vocab._terms.items())
[(u'object1', <UtilityTerm object1, instance of Object>),
 (u'object2', <UtilityTerm object2, instance of Object>),
 (u'object3', <UtilityTerm object3, instance of Object>)]

Sometimes it is desirable to only select the name of a utility. For this purpose a nameOnly argument was added to the constructor, in which case the UtilityTerm's value is not the utility itself but the name of the utility.

>>> vocab = UtilityVocabulary(None, interface=IObject, nameOnly=True)
>>> pprint.pprint([term.value for term in vocab])
[u'object1', u'object2', u'object3']

Base classes

Implemented Interfaces

Attributes/Properties

Methods

Known Subclasses