Module Menu and ZCML Directive Details

This document provides an overview of all browser-presentation related objects.

menu.getAllTextOfInterface()

Get all searchable text from an interface

>>> import zope.interface
>>> import zope.schema
>>> class IFoo(zope.interface.Interface):
...     '''foo'''
...
...     def bar(self):
...         '''bar'''
...
...     blah = zope.interface.Attribute('blah', 'blah')
...
...     field = zope.schema.Field(
...         title = u'title', description = u'description')

Now get the text. Note that there is no particular order during the text collection.

>>> from zope.app.apidoc.ifacemodule.menu import getAllTextOfInterface
>>> text = getAllTextOfInterface(IFoo)
>>> u'foo' in text
True
>>> u'bar' in text
True
>>> u'blah' in text
True
>>> u'field' in text
True
>>> u'title' in text
True
>>> u'description' in text
True

Menu class

This is the menu class for the Interface Documentation Module.

The menu allows one to look for interfaces by full-text search or partial names. The findInterfaces method provides a simple search mechanism.

Before we can test the method, let’s create a menu.Menu instance:

>>> from zope.interface.interfaces import IElement, IAttribute

>>> from zope.app.apidoc.ifacemodule.menu import Menu
>>> menu = Menu()
>>> menu.context = {'IElement': IElement, 'IAttribute': IAttribute}
>>> menu.request = {'name_only': 'on', 'search_str': ''}

Now let’s see how successful our searches are:

>>> menu.request['search_str'] = 'Elem'
>>> from pprint import pprint
>>> pprint(menu.findInterfaces(), width=1)
[{'name': 'IElement',
  'url': './IElement/index.html'}]

>>> menu.request['search_str'] = 'I'
>>> pprint(menu.findInterfaces(), width=1)
[{'name': 'IAttribute',
  'url': './IAttribute/index.html'},
 {'name': 'IElement',
  'url': './IElement/index.html'}]

Now using the full text search:

>>> del menu.request['name_only']

>>> menu.request['search_str'] = 'object'
>>> pprint(menu.findInterfaces(), width=1)
[{'name': 'IAttribute',
  'url': './IAttribute/index.html'},
 {'name': 'IElement',
  'url': './IElement/index.html'}]

>>> menu.request['search_str'] = 'Stores'
>>> pprint(menu.findInterfaces(), width=1)
[{'name': 'IAttribute',
  'url': './IAttribute/index.html'}]

InterfaceDetails class

This view provides many details about an interface. Most methods of the class actually use the public inspection API.

Before we can test the view, we need to create an interesting setup, so that the view can provide some useful data. Let’s start by defining a complex interface:

>>> class IFoo(zope.interface.Interface):
...     """This is the Foo interface
...
...     More description here...
...     """
...     foo = zope.interface.Attribute('This is foo.')
...     bar = zope.interface.Attribute('This is bar.')
...
...     title = zope.schema.TextLine(
...         description=u'Title',
...         required=True,
...         default=u'Foo')
...
...     description = zope.schema.Text(
...         description=u'Desc',
...         required=False,
...         default=u'Foo.')
...
...     def blah():
...         """This is blah."""
...
...     def get(key, default=None):
...         """This is get."""

Let’s now create another interface IBar and make Foo an adapter from IBar to IFoo:

>>> class IBar(zope.interface.Interface):
...     pass

>>> @zope.interface.implementer(IFoo)
... class Foo(object):
...     pass

>>> from zope import component as ztapi
>>> ztapi.provideAdapter(adapts=(IBar,), provides=IFoo, factory=Foo)

>>> from zope.app.apidoc.classregistry import classRegistry
>>> classRegistry['__builtin__.Foo'] = Foo

Let’s also register a factory for Foo

>>> from zope.component.interfaces import IFactory
>>> from zope.component.factory import Factory
>>> ztapi.provideUtility(Factory(Foo, title='Foo Factory'), IFactory,
...                      'FooFactory')

and a utility providing IFoo:

>>> ztapi.provideUtility(Foo(), IFoo, 'The Foo')

Now that the initial setup is done, we can create an interface that is located in the interface documentation module

>>> ifacemodule = apidoc.get('Interface')
>>> from zope.location import LocationProxy
>>> iface = LocationProxy(IFoo, ifacemodule, 'IFoo')

and finally the details view:

>>> from zope.publisher.browser import TestRequest
>>> from zope.app.apidoc.ifacemodule.browser import InterfaceDetails
>>> details = InterfaceDetails(iface, TestRequest())

InterfaceDetails.getId()

Return the id of the field as it is defined for the interface utility.

>>> details.getId()
'IFoo'

InterfaceDetails.getDoc()

Return the main documentation string of the interface.

>>> details.getDoc()[:32]
u'<p>This is the Foo interface</p>'

InterfaceDetails.getBases()

Get all bases of this class

>>> details.getBases()
['zope.interface.Interface']

InterfaceDetails.getTypes()

Return a list of interface types that are specified for this interface.

Initially we do not have any types

>>> details.getTypes()
[]

but when I create and assign a type to the interface

>>> class IMyType(zope.interface.interfaces.IInterface):
...     pass

>>> zope.interface.directlyProvides(IFoo, IMyType)

we get a result:

>>> pprint(details.getTypes(), width=1)
[{'name': 'IMyType',
  'path': '__builtin__.IMyType'}]

InterfaceDetails.getAttributes()

Return a list of attributes in the order they were specified.

>>> pprint(sorted(details.getAttributes(), key=lambda x: x['name']))
[{'doc': u'<p>This is bar.</p>\n',
  'name': 'bar'},
 {'doc': u'<p>This is foo.</p>\n',
  'name': 'foo'}]

InterfaceDetails.getMethods()

Return a list of methods in the order they were specified.

>>> pprint(sorted(details.getMethods(), key=lambda x: x['name']))
[{'doc': u'<p>This is blah.</p>\n',
  'name': 'blah',
  'signature': '()'},
 {'doc': u'<p>This is get.</p>\n',
  'name': 'get',
  'signature': '(key, default=None)'}]

InterfaceDetails.getFields()

Return a list of fields in required + alphabetical order.

The required attributes are listed first, then the optional attributes.

>>> pprint(details.getFields(), width=1)
[{'class': {'name': 'TextLine',
            'path': 'zope/schema/_bootstrapfields/TextLine'},
  'default': "u'Foo'",
  'description': u'<p>Title</p>\n',
  'iface': {'id': 'zope.schema.interfaces.ITextLine',
            'name': 'ITextLine'},
  'name': 'title',
  'required': True,
  'required_string': u'required',
  'title': u''},
 {'class': {'name': 'Text',
            'path': 'zope/schema/_bootstrapfields/Text'},
  'default': "u'Foo.'",
  'description': u'<p>Desc</p>\n',
  'iface': {'id': 'zope.schema.interfaces.IText',
            'name': 'IText'},
  'name': 'description',
  'required': False,
  'required_string': u'optional',
  'title': u''}]

InterfaceDetails.getSpecificRequiredAdapters()

Get adapters where this interface is required.

>>> pprint(details.getSpecificRequiredAdapters())
[]

InterfaceDetails.getExtendedRequiredAdapters()

Get adapters where this interface is required.

>>> pprint(details.getExtendedRequiredAdapters())
[]

Note that this includes all interfaces registered for zope.interface.interface.Interface.

InterfaceDetails.getGenericRequiredAdapters()

Get adapters where this interface is required.

>>> required = details.getGenericRequiredAdapters()
>>> len(required) >= 10
True

InterfaceDetails.getProvidedAdapters()

Get adapters where this interface is provided.

>>> pprint(details.getProvidedAdapters(), width=1)
[{'doc': u'',
  'factory': '__builtin__.Foo',
  'factory_url': None,
  'name': u'',
  'provided': {'module': '__builtin__',
               'name': 'IFoo'},
  'required': [{'isInterface': True,
                'isType': False,
                'module': '__builtin__',
                'name': 'IBar'}],
  'zcml': None}]

InterfaceDetails.getClasses()

Get the classes that implement this interface.

>>> pprint(details.getClasses(), width=1)
[{'path': '__builtin__.Foo',
  'url': '__builtin__/Foo'}]

InterfaceDetails.getFactories()

Return the factories, who will provide objects implementing this interface.

>>> pprint(details.getFactories())
[{'description': u'',
  'name': u'FooFactory',
  'title': 'Foo Factory',
  'url': None}]

InterfaceDetails.getUtilities()

Return all utilities that provide this interface.

>>> pprint(details.getUtilities())
[{'iface_id': '__builtin__.IFoo',
  'name': u'The Foo',
  'path': '__builtin__.Foo',
  'url': None,
  'url_name': 'VGhlIEZvbw=='}]