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:
>>> 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']
interface
(type:
InterfaceClass
)
<InterfaceClass zope.interface.Interface>
nameOnly
(type:
bool
)
False
getTerm(value)
See zope.schema.interfaces.IBaseVocabulary
getTermByToken(token)
See zope.schema.interfaces.IVocabularyTokenized