The Utilities Documentation Module

This documentation module organizes all registered utilities by their provided interface and then by the name of the utility.


This class represents the documentation of all utility interfaces. The items of the container are all UtilityInterface instances.

Let’s start by creating a utility documentation module:

>>> from import UtilityModule
>>> module = UtilityModule()

To make the documentation module useful, we have to register a utility, so why not the documentation module itself?

>>> from import IDocumentationModule
>>> from zope import component as ztapi
>>> ztapi.provideUtility(module, IDocumentationModule, 'Utility')

Now we can get a single utility interface by path:

>>> module.get('')
< ...>

and list all available interfaces:

>>> module.items()
  < ...>),
  < ...>),


Representation of an interface a utility provides.

First we create a utility interface documentation instance:

>>> from import UtilityInterface
>>> ut_iface = UtilityInterface(
...     module,
...     '',
...     IDocumentationModule)

Now we can get the utility:

>>> ut_iface.get('Utility').component
< object at ...>

Unnamed utilities are special, since they can be looked up in different ways:

>>> ztapi.provideUtility(module, IDocumentationModule, '')
>>> ut_iface.get('').component
< object at ...>
>>> from import NONAME
>>> ut_iface.get(NONAME).component
< object at ...>

If you try to get a non-existent utility, None is returned:

>>> ut_iface.get('foo') is None

You can get a list of available utilities as well, of course:

>>> ut_iface.items()
 (b'VXRpbGl0eQ==', <...apidoc.utilitymodule.utilitymodule.Utility ...>),
 (b'X19ub25hbWVfXw==', <...apidoc.utilitymodule.utilitymodule.Utility ...>)]

Bu what are those strange names? Since utility names can be any string, it is hard to deal with them in a URL. Thus the system will advertise and use the names in their BASE64 encoded form. However, because it is easier in the Python API to use the real utility names, utilities can be looked up in their original form as well.

Encoding and Decoding Names

The utility names are en- and decoded using two helper methods:

>>> from import encodeName
>>> from import decodeName

Round trips of encoding and decoding should be possible:

>>> encoded = encodeName(u'Some Utility')
>>> encoded
>>> decodeName(encoded)
u'Some Utility'

If a string is not encoded, the decoding process will simply return the original string:

>>> decodeName(u'Some Utility')
u'Some Utility'