zope.interface 3.3.0.1

Declaring implemented interfaces

The most common way to declare interfaces is using the implements function in a class statement:

>>> class Foo:
...     zope.interface.implements(IFoo)
...
...     def __init__(self, x=None):
...         self.x = x
...
...     def bar(self, q, r=None):
...         return q, r, self.x
...
...     def __repr__(self):
...         return "Foo(%s)" % self.x

In this example, we declared that Foo implements IFoo. This means that instances of Foo provide IFoo. Having made this declaration, there are several ways we can introspect the declarations. First, we can ask an interface whether it is implemented by a class:

>>> IFoo.implementedBy(Foo)
True

And we can ask whether an interface is provided by an object:

>>> foo = Foo()
>>> IFoo.providedBy(foo)
True

Of course, Foo doesn’t provide IFoo, it implements it:

>>> IFoo.providedBy(Foo)
False

We can also ask what interfaces are implemented by an object:

>>> list(zope.interface.implementedBy(Foo))
[<InterfaceClass __main__.IFoo>]

It’s an error to ask for interfaces implemented by a non-callable object:

>>> IFoo.implementedBy(foo)
Traceback (most recent call last):
...
TypeError: ('ImplementedBy called for non-factory', Foo(None))

>>> list(zope.interface.implementedBy(foo))
Traceback (most recent call last):
...
TypeError: ('ImplementedBy called for non-factory', Foo(None))

Similarly, we can ask what interfaces are provided by an object:

>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __main__.IFoo>]
>>> list(zope.interface.providedBy(Foo))
[]

We can declare interfaces implemented by other factories (besides classes). We do this using a Python-2.4-style decorator named implementer. In versions of Python before 2.4, this looks like:

>>> def yfoo(y):
...     foo = Foo()
...     foo.y = y
...     return foo
>>> yfoo = zope.interface.implementer(IFoo)(yfoo)

>>> list(zope.interface.implementedBy(yfoo))
[<InterfaceClass __main__.IFoo>]

Note that the implementer decorator may modify it’s argument. Callers should not assume that a new object is created.

Also note that, at least for now, implementer can’t be used with classes:

>>> zope.interface.implementer(IFoo)(Foo)
... # doctest: +NORMALIZE_WHITESPACE
Traceback (most recent call last):
  ...
TypeError: Can't use implementer with classes.
Use one of the class-declaration functions instead.

Declaring provided interfaces

We can declare interfaces directly provided by objects. Suppose that we want to document what the __init__ method of the Foo class does. It’s not really part of IFoo. You wouldn’t normally call the __init__ method on Foo instances. Rather, the __init__ method is part of the Foo’s __call__ method:

>>> class IFooFactory(zope.interface.Interface):
...     """Create foos"""
...
...     def __call__(x=None):
...         """Create a foo
...
...         The argument provides the initial value for x ...
...         """

It’s the class that provides this interface, so we declare the interface on the class:

>>> zope.interface.directlyProvides(Foo, IFooFactory)

And then, we’ll see that Foo provides some interfaces:

>>> list(zope.interface.providedBy(Foo))
[<InterfaceClass __main__.IFooFactory>]
>>> IFooFactory.providedBy(Foo)
True

Declaring class interfaces is common enough that there’s a special declaration function for it, classProvides, that allows the declaration from within a class statement:

>>> class Foo2:
...     zope.interface.implements(IFoo)
...     zope.interface.classProvides(IFooFactory)
...
...     def __init__(self, x=None):
...         self.x = x
...
...     def bar(self, q, r=None):
...         return q, r, self.x
...
...     def __repr__(self):
...         return "Foo(%s)" % self.x

>>> list(zope.interface.providedBy(Foo2))
[<InterfaceClass __main__.IFooFactory>]
>>> IFooFactory.providedBy(Foo2)
True

There’s a similar function, moduleProvides, that supports interface declarations from within module definitions. For example, see the use of moduleProvides call in zope.interface.__init__, which declares that the package zope.interface provides IInterfaceDeclaration.

Sometimes, we want to declare interfaces on instances, even though those instances get interfaces from their classes. Suppose we create a new interface, ISpecial:

>>> class ISpecial(zope.interface.Interface):
...     reason = zope.interface.Attribute("Reason why we're special")
...     def brag():
...         "Brag about being special"

We can make an existing foo instance special by providing reason and brag attributes:

>>> foo.reason = 'I just am'
>>> def brag():
...      return "I'm special!"
>>> foo.brag = brag
>>> foo.reason
'I just am'
>>> foo.brag()
"I'm special!"

and by declaring the interface:

>>> zope.interface.directlyProvides(foo, ISpecial)

then the new interface is included in the provided interfaces:

>>> ISpecial.providedBy(foo)
True
>>> list(zope.interface.providedBy(foo))
[<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]

We can find out what interfaces are directly provided by an object:

>>> list(zope.interface.directlyProvidedBy(foo))
[<InterfaceClass __main__.ISpecial>]

>>> newfoo = Foo()
>>> list(zope.interface.directlyProvidedBy(newfoo))
[]

Inherited declarations

Normally, declarations are inherited:

>>> class SpecialFoo(Foo):
...     zope.interface.implements(ISpecial)
...     reason = 'I just am'
...     def brag(self):
...         return "I'm special because %s" % self.reason

>>> list(zope.interface.implementedBy(SpecialFoo))
[<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]

>>> list(zope.interface.providedBy(SpecialFoo()))
[<InterfaceClass __main__.ISpecial>, <InterfaceClass __main__.IFoo>]

Sometimes, you don’t want to inherit declarations. In that case, you can use implementsOnly, instead of implements:

>>> class Special(Foo):
...     zope.interface.implementsOnly(ISpecial)
...     reason = 'I just am'
...     def brag(self):
...         return "I'm special because %s" % self.reason

>>> list(zope.interface.implementedBy(Special))
[<InterfaceClass __main__.ISpecial>]

>>> list(zope.interface.providedBy(Special()))
[<InterfaceClass __main__.ISpecial>]

External declarations

Normally, we make implementation declarations as part of a class definition. Sometimes, we may want to make declarations from outside the class definition. For example, we might want to declare interfaces for classes that we didn’t write. The function classImplements can be used for this purpose:

>>> class C:
...     pass

>>> zope.interface.classImplements(C, IFoo)
>>> list(zope.interface.implementedBy(C))
[<InterfaceClass __main__.IFoo>]

We can use classImplementsOnly to exclude inherited interfaces:

>>> class C(Foo):
...     pass

>>> zope.interface.classImplementsOnly(C, ISpecial)
>>> list(zope.interface.implementedBy(C))
[<InterfaceClass __main__.ISpecial>]

Declaration Objects

When we declare interfaces, we create declaration objects. When we query declarations, declaration objects are returned:

>>> type(zope.interface.implementedBy(Special))
<class 'zope.interface.declarations.Implements'>

Declaration objects and interface objects are similar in many ways. In fact, they share a common base class. The important thing to realize about them is that they can be used where interfaces are expected in declarations. Here’s a silly example:

>>> class Special2(Foo):
...     zope.interface.implementsOnly(
...          zope.interface.implementedBy(Foo),
...          ISpecial,
...          )
...     reason = 'I just am'
...     def brag(self):
...         return "I'm special because %s" % self.reason

The declaration here is almost the same as zope.interface.implements(ISpecial), except that the order of interfaces in the resulting declaration is different:

>>> list(zope.interface.implementedBy(Special2))
[<InterfaceClass __main__.IFoo>, <InterfaceClass __main__.ISpecial>]

Inheritance of attribute specifications

An interface may override attribute definitions from base interfaces. If two base interfaces define the same attribute, the attribute is inherited from the most specific interface. For example, with:

>>> class IBase(zope.interface.Interface):
...
...     def foo():
...         "base foo doc"

>>> class IBase1(IBase):
...     pass

>>> class IBase2(IBase):
...
...     def foo():
...         "base2 foo doc"

>>> class ISub(IBase1, IBase2):
...     pass

ISub’s definition of foo is the one from IBase2, since IBase2 is more specific that IBase:

>>> ISub['foo'].__doc__
'base2 foo doc'

Note that this differs from a depth-first search.

Sometimes, it’s useful to ask whether an interface defines an attribute directly. You can use the direct method to get a directly defined definitions:

>>> IBase.direct('foo').__doc__
'base foo doc'

>>> ISub.direct('foo')

Specifications

Interfaces and declarations are both special cases of specifications. What we described above for interface inheritance applies to both declarations and specifications. Declarations actually extend the interfaces that they declare:

>>> class Baz:
...     zope.interface.implements(IBaz)

>>> baz_implements = zope.interface.implementedBy(Baz)
>>> baz_implements.__bases__
(<InterfaceClass __main__.IBaz>,)

>>> baz_implements.extends(IFoo)
True

>>> baz_implements.isOrExtends(IFoo)
True
>>> baz_implements.isOrExtends(baz_implements)
True

Specifications (interfaces and declarations) provide an __sro__ that lists the specification and all of it’s ancestors:

>>> baz_implements.__sro__
(<implementedBy __main__.Baz>,
 <InterfaceClass __main__.IBaz>,
 <InterfaceClass __main__.IFoo>,
 <InterfaceClass __main__.IBlat>,
 <InterfaceClass zope.interface.Interface>)

Finding out what, if anything, is registered

We can ask if there is an adapter registered for a collection of interfaces. This is different than lookup, because it looks for an exact match.

>>> print registry.registered([IR1], IP1)
11

>>> print registry.registered([IR1], IP2)
12

>>> print registry.registered([IR1], IP2, 'bob')
Bob's 12

>>> print registry.registered([IR2], IP1)
21

>>> print registry.registered([IR2], IP2)
None

In the last example, None was returned because nothing was registered exactly for the given interfaces.

lookup1

Lookup of single adapters is common enough that there is a specialized version of lookup that takes a single required interface:

>>> registry.lookup1(IR2, IP1, '')
21
>>> registry.lookup1(IR2, IP1)
21

Actual Adaptation

The adapter registry is intended to support adaptation, where one object that implements an interface is adapted to another object that supports a different interface. The adapter registry supports the computation of adapters. In this case, we have to register adapter factories:

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

 >>> class X:
 ...     zope.interface.implements(IR)

 >>> class Y:
 ...     zope.interface.implements(IP1)
 ...     def __init__(self, context):
 ...         self.context = context

>>> registry.register([IR], IP1, '', Y)

In this case, we registered a class as the factory. Now we can call queryAdapter to get the adapted object:

>>> x = X()
>>> y = registry.queryAdapter(x, IP1)
>>> y.__class__.__name__
'Y'
>>> y.context is x
True

We can register and lookup by name too:

>>> class Y2(Y):
...     pass

>>> registry.register([IR], IP1, 'bob', Y2)
>>> y = registry.queryAdapter(x, IP1, 'bob')
>>> y.__class__.__name__
'Y2'
>>> y.context is x
True

When the adapter factory produces None, then this is treated as if no adapter has been found. This allows us to prevent adaptation (when desired) and let the adapter factory determine whether adaptation is possible based on the state of the object being adapted.

>>> def factory(context):
...     if context.name == 'object':
...         return 'adapter'
...     return None

>>> class Object(object):
...     zope.interface.implements(IR)
...     name = 'object'

>>> registry.register([IR], IP1, 'conditional', factory)
>>> obj = Object()
>>> registry.queryAdapter(obj, IP1, 'conditional')
'adapter'
>>> obj.name = 'no object'
>>> registry.queryAdapter(obj, IP1, 'conditional') is None
True
>>> registry.queryAdapter(obj, IP1, 'conditional', 'default')
'default'

An alternate method that provides the same function as queryAdapter() is adapter_hook():

>>> y = registry.adapter_hook(IP1, x)
>>> y.__class__.__name__
'Y'
>>> y.context is x
True
>>> y = registry.adapter_hook(IP1, x, 'bob')
>>> y.__class__.__name__
'Y2'
>>> y.context is x
True

The adapter_hook() simply switches the order of the object and interface arguments. It is used to hook into the interface call mechanism.

Default Adapters

Sometimes, you want to provide an adapter that will adapt anything. For that, provide None as the required interface:

>>> registry.register([None], IP1, '', 1)

then we can use that adapter for interfaces we don’t have specific adapters for:

>>> class IQ(zope.interface.Interface):
...     pass
>>> registry.lookup([IQ], IP1, '')
1

Of course, specific adapters are still used when applicable:

>>> registry.lookup([IR2], IP1, '')
21

Class adapters

You can register adapters for class declarations, which is almost the same as registering them for a class:

>>> registry.register([zope.interface.implementedBy(C2)], IP1, '', 'C21')
>>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
'C21'

Dict adapters

At some point it was impossible to register dictionary-based adapters due a bug. Let’s make sure this works now:

>>> adapter = {}
>>> registry.register((), IQ, '', adapter)
>>> registry.lookup((), IQ, '') is adapter
True

Unregistering

You can unregister by registering None, rather than an object:

>>> registry.register([zope.interface.implementedBy(C2)], IP1, '', None)
>>> registry.lookup([zope.interface.implementedBy(C2)], IP1, '')
21

Of course, this means that None can’t be registered. This is an exception to the statement, made earlier, that the registry doesn’t care what gets registered.

Multi-adaptation

You can adapt multiple objects:

>>> class Q:
...     zope.interface.implements(IQ)

As with single adapters, we register a factory, which is often a class:

>>> class IM(zope.interface.Interface):
...     pass
>>> class M:
...     zope.interface.implements(IM)
...     def __init__(self, x, q):
...         self.x, self.q = x, q
>>> registry.register([IR, IQ], IM, '', M)

And then we can call queryMultiAdapter to compute an adapter:

>>> q = Q()
>>> m = registry.queryMultiAdapter((x, q), IM)
>>> m.__class__.__name__
'M'
>>> m.x is x and m.q is q
True

and, of course, we can use names:

>>> class M2(M):
...     pass
>>> registry.register([IR, IQ], IM, 'bob', M2)
>>> m = registry.queryMultiAdapter((x, q), IM, 'bob')
>>> m.__class__.__name__
'M2'
>>> m.x is x and m.q is q
True

Default Adapters

As with single adapters, you can define default adapters by specifying None for the first specification:

>>> registry.register([None, IQ], IP2, '', 'q2')
>>> registry.lookup([IS, IQ], IP2, '')
'q2'

Listing named adapters

Adapters are named. Sometimes, it’s useful to get all of the named adapters for given interfaces:

>>> adapters = list(registry.lookupAll([IR1], IP1))
>>> adapters.sort()
>>> adapters
[(u'', 11), (u'bob', "Bob's 12")]

This works for multi-adapters too:

>>> registry.register([IR1, IQ2], IP2, 'bob', '1q2 for bob')
>>> adapters = list(registry.lookupAll([IR2, IQ2], IP1))
>>> adapters.sort()
>>> adapters
[(u'', '1q22'), (u'bob', '1q2 for bob')]

And even null adapters:

>>> registry.register([], IP2, 'bob', 3)
>>> adapters = list(registry.lookupAll([], IP1))
>>> adapters.sort()
>>> adapters
[(u'', 2), (u'bob', 3)]

Unregistering subscribers

We can unregister subscribers. When unregistering a subscriber, we can unregister a specific subscriber:

>>> registry.unsubscribe([IR1], IP1, 'sub11')
>>> registry.subscriptions([IR1], IP1)
['sub_1', 'sub12 1', 'sub12 2']

If we don’t specify a value, then all subscribers matching the given interfaces will be unsubscribed:

>>> registry.unsubscribe([IR1], IP2)
>>> registry.subscriptions([IR1], IP1)
['sub_1']

Subscription adapters

We normally register adapter factories, which then allow us to compute adapters, but with subscriptions, we get multiple adapters. Here’s an example of multiple-object subscribers:

>>> registry.subscribe([IR, IQ], IM, M)
>>> registry.subscribe([IR, IQ], IM, M2)

>>> subscribers = registry.subscribers((x, q), IM)
>>> len(subscribers)
2
>>> class_names = [s.__class__.__name__ for s in subscribers]
>>> class_names.sort()
>>> class_names
['M', 'M2']
>>> [(s.x is x and s.q is q) for s in subscribers]
[True, True]

adapter factory subcribers can’t return None values

>>> def M3(x, y):
...     return None

>>> registry.subscribe([IR, IQ], IM, M3)
>>> subscribers = registry.subscribers((x, q), IM)
>>> len(subscribers)
2

Handlers

A handler is a subscriber factory that doesn’t produce any normal output. It returns None. A handler is unlike adapters in that it does all of its work when the factory is called.

To register a handler, simply provide None as the provided interface:

>>> def handler(event):
...     print 'handler', event

>>> registry.subscribe([IR1], None, handler)
>>> registry.subscriptions([IR1], None) == [handler]
True