Skip to main content

Zope 3 Interface Infrastructure

Project description

Interfaces are a mechanism for labeling objects as conforming to a given API or contract.

zope.interface Package Changes

3.3.0.1 (2007/01/03)

Bug Fixes

  • Made a reference to OverflowWarning, which disappeared in Python 2.5, conditional.

3.3.0 (2007/01/03)

New Features

  • The adapter-lookup algorithim was refactored to make it much simpler and faster.

    Also, more of the adapter-lookup logic is implemented in C, making debugging of application code easier, since there is less infrastructre code to step through.

  • We now treat objects without interafce declarations as if they declared that they provide zope.interface.Interface.

  • There are a number of richer new adapter-registration interfaces that provide greater control and introspection.

  • Added a new interface decorator to zope.interface that allows the setting of tagged values on an interface at definition time (see zope.interface.taggedValue).

Bug Fixes

  • A bug in multi-adapter lookup sometimes caused incorrect adapters to be returned.

zope.interface version 3.2.0.2 (2006/04/15)

  • Fix packaging bug: ‘package_dir’ must be a relative path.

zope.interface version 3.2.0.1 (2006/04/14)

  • Packaging change: suppress inclusion of ‘setup.cfg’ in ‘sdist’ builds.

zope.interface version 3.2.0 (2006/01/05)

  • Corresponds to the verison of the zope.interface package shipped as part of the Zope 3.2.0 release.

  • TODO: note other changes

zope.interface version 3.1.0 (2005/10/03)

  • Corresponds to the verison of the zope.interface package shipped as part of the Zope 3.1.0 release.

  • TODO: note other changes

  • Made attribute resolution order consistent with component lookup order, i.e. new-style class MRO semantics.

  • Deprecated ‘isImplementedBy’ and ‘isImplementedByInstancesOf’ APIs in favor of ‘implementedBy’ and ‘providedBy’.

zope.interface version 3.0.1 (2005/07/27)

  • Corresponds to the verison of the zope.interface package shipped as part of the Zope X3.0.1 release.

  • Fixed a bug reported by James Knight, which caused adapter registries to fail occasionally to reflect declaration changes.

zope.interface version 3.0.0 (2004/11/07)

  • Corresponds to the verison of the zope.interface package shipped as part of the Zope X3.0.0 release.

Detailed Documentation

Interfaces

Interfaces are objects that specify (document) the external behavior of objects that “provide” them. An interface specifies behavior through:

  • Informal documentation in a doc string

  • Attribute definitions

  • Invariants, which are conditions that must hold for objects that provide the interface

Attribute definitions specify specific attributes. They define the attribute name and provide documentation and constraints of attribute values. Attribute definitions can take a number of forms, as we’ll see below.

Defining interfaces

Interfaces are defined using Python class statements:

>>> import zope.interface
>>> class IFoo(zope.interface.Interface):
...    """Foo blah blah"""
...
...    x = zope.interface.Attribute("""X blah blah""")
...
...    def bar(q, r=None):
...        """bar blah blah"""

In the example above, we’ve created an interface, IFoo. We subclassed zope.interface.Interface, which is an ancestor interface for all interfaces, much as object is an ancestor of all new-style classes [1]. The interface is not a class, it’s an Interface, an instance of InterfaceClass:

>>> type(IFoo)
<class 'zope.interface.interface.InterfaceClass'>

We can ask for the interface’s documentation:

>>> IFoo.__doc__
'Foo blah blah'

and its name:

>>> IFoo.__name__
'IFoo'

and even its module:

>>> IFoo.__module__
'__main__'

The interface defined two attributes:

x

This is the simplest form of attribute definition. It has a name and a doc string. It doesn’t formally specify anything else.

bar

This is a method. A method is defined via a function definition. A method is simply an attribute constrained to be a callable with a particular signature, as provided by the function definition.

Note that bar doesn’t take a self argument. Interfaces document how an object is used. When calling instance methods, you don’t pass a self argument, so a self argument isn’t included in the interface signature. The self argument in instance methods is really an implementation detail of Python instances. Other objects, besides instances can provide interfaces and their methods might not be instance methods. For example, modules can provide interfaces and their methods are usually just functions. Even instances can have methods that are not instance methods.

You can access the attributes defined by an interface using mapping syntax:

>>> x = IFoo['x']
>>> type(x)
<class 'zope.interface.interface.Attribute'>
>>> x.__name__
'x'
>>> x.__doc__
'X blah blah'

>>> IFoo.get('x').__name__
'x'

>>> IFoo.get('y')

You can use in to determine if an interface defines a name:

>>> 'x' in IFoo
True

You can iterate over interfaces to get the names they define:

>>> names = list(IFoo)
>>> names.sort()
>>> names
['bar', 'x']

Remember that interfaces aren’t classes. You can’t access attribute definitions as attributes of interfaces:

>>> IFoo.x
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
AttributeError: 'InterfaceClass' object has no attribute 'x'

Methods provide access to the method signature:

>>> bar = IFoo['bar']
>>> bar.getSignatureString()
'(q, r=None)'
TODO

Methods really should have a better API. This is something that needs to be improved.

Declaring interfaces

Having defined interfaces, we can declare that objects provide them. Before we describe the details, lets define some terms:

provide

We say that objects provide interfaces. If an object provides an interface, then the interface specifies the behavior of the object. In other words, interfaces specify the behavior of the objects that provide them.

implement

We normally say that classes implement interfaces. If a class implements an interface, then the instances of the class provide the interface. Objects provide interfaces that their classes implement [2]. (Objects can provide interfaces directly, in addition to what their classes implement.)

It is important to note that classes don’t usually provide the interfaces that they implement.

We can generalize this to factories. For any callable object we can declare that it produces objects that provide some interfaces by saying that the factory implements the interfaces.

Now that we’ve defined these terms, we can talk about the API for declaring interfaces.

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>]

Interface Inheritance

Interfaces can extend other interfaces. They do this simply by listing the other interfaces as base interfaces:

>>> class IBlat(zope.interface.Interface):
...     """Blat blah blah"""
...
...     y = zope.interface.Attribute("y blah blah")
...     def eek():
...         """eek blah blah"""

>>> IBlat.__bases__
(<InterfaceClass zope.interface.Interface>,)

>>> class IBaz(IFoo, IBlat):
...     """Baz blah"""
...     def eek(a=1):
...         """eek in baz blah"""
...

>>> IBaz.__bases__
(<InterfaceClass __main__.IFoo>, <InterfaceClass __main__.IBlat>)

>>> names = list(IBaz)
>>> names.sort()
>>> names
['bar', 'eek', 'x', 'y']

Note that IBaz overrides eek:

>>> IBlat['eek'].__doc__
'eek blah blah'
>>> IBaz['eek'].__doc__
'eek in baz blah'

We were careful to override eek in a compatible way. When extending an interface, the extending interface should be compatible [3] with the extended interfaces.

We can ask whether one interface extends another:

>>> IBaz.extends(IFoo)
True
>>> IBlat.extends(IFoo)
False

Note that interfaces don’t extend themselves:

>>> IBaz.extends(IBaz)
False

Sometimes we wish they did, but we can, instead use isOrExtends:

>>> IBaz.isOrExtends(IBaz)
True
>>> IBaz.isOrExtends(IFoo)
True
>>> IFoo.isOrExtends(IBaz)
False

When we iterate over an interface, we get all of the names it defines, including names defined by base interfaces. Sometimes, we want just the names defined by the interface directly. We bane use the names method for that:

>>> list(IBaz.names())
['eek']
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>)

Tagged Values

Interfaces and attribute descriptions support an extension mechanism, borrowed from UML, called “tagged values” that lets us store extra data:

>>> IFoo.setTaggedValue('date-modified', '2004-04-01')
>>> IFoo.setTaggedValue('author', 'Jim Fulton')
>>> IFoo.getTaggedValue('date-modified')
'2004-04-01'
>>> IFoo.queryTaggedValue('date-modified')
'2004-04-01'
>>> IFoo.queryTaggedValue('datemodified')
>>> tags = list(IFoo.getTaggedValueTags())
>>> tags.sort()
>>> tags
['author', 'date-modified']

Function attributes are converted to tagged values when method attribute definitions are created:

>>> class IBazFactory(zope.interface.Interface):
...     def __call__():
...         "create one"
...     __call__.return_type = IBaz

>>> IBazFactory['__call__'].getTaggedValue('return_type')
<InterfaceClass __main__.IBaz>

Tagged values can also be defined from within an interface definition:

>>> class IWithTaggedValues(zope.interface.Interface):
...     zope.interface.taggedValue('squish', 'squash')
>>> IWithTaggedValues.getTaggedValue('squish')
'squash'

Invariants

Interfaces can express conditions that must hold for objects that provide them. These conditions are expressed using one or more invariants. Invariants are callable objects that will be called with an object that provides an interface. An invariant raises an Invalid exception if the condition doesn’t hold. Here’s an example:

>>> class RangeError(zope.interface.Invalid):
...     """A range has invalid limits"""
...     def __repr__(self):
...         return "RangeError(%r)" % self.args

>>> def range_invariant(ob):
...     if ob.max < ob.min:
...         raise RangeError(ob)

Given this invariant, we can use it in an interface definition:

>>> class IRange(zope.interface.Interface):
...     min = zope.interface.Attribute("Lower bound")
...     max = zope.interface.Attribute("Upper bound")
...
...     zope.interface.invariant(range_invariant)

Interfaces have a method for checking their invariants:

>>> class Range(object):
...     zope.interface.implements(IRange)
...
...     def __init__(self, min, max):
...         self.min, self.max = min, max
...
...     def __repr__(self):
...         return "Range(%s, %s)" % (self.min, self.max)

>>> IRange.validateInvariants(Range(1,2))
>>> IRange.validateInvariants(Range(1,1))
>>> IRange.validateInvariants(Range(2,1))
Traceback (most recent call last):
...
RangeError: Range(2, 1)

If you have multiple invariants, you may not want to stop checking after the first error. If you pass a list to validateInvariants, then a single Invalid exception will be raised with the list of exceptions as it’s argument:

>>> errors = []
>>> IRange.validateInvariants(Range(2,1), errors)
Traceback (most recent call last):
...
Invalid: [RangeError(Range(2, 1))]

And the list will be filled with the individual exceptions:

>>> errors
[RangeError(Range(2, 1))]


>>> del errors[:]

Adaptation

Interfaces can be called to perform adaptation.

The sematics based on those of the PEP 246 adapt function.

If an object cannot be adapted, then a TypeError is raised:

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

>>> I(0)
Traceback (most recent call last):
...
TypeError: ('Could not adapt', 0, <InterfaceClass __main__.I>)

unless an alternate value is provided as a second positional argument:

>>> I(0, 'bob')
'bob'

If an object already implements the interface, then it will be returned:

>>> class C(object):
...     zope.interface.implements(I)

>>> obj = C()
>>> I(obj) is obj
True

If an object implements __conform__, then it will be used:

>>> class C(object):
...     zope.interface.implements(I)
...     def __conform__(self, proto):
...          return 0

>>> I(C())
0

Adapter hooks (see __adapt__) will also be used, if present:

>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
...     if obj == 0:
...         return 42
>>> adapter_hooks.append(adapt_0_to_42)
>>> I(0)
42
>>> adapter_hooks.remove(adapt_0_to_42)
>>> I(0)
Traceback (most recent call last):
...
TypeError: ('Could not adapt', 0, <InterfaceClass __main__.I>)

__adapt__

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

Interfaces implement the PEP 246 __adapt__ method.

This method is normally not called directly. It is called by the PEP 246 adapt framework and by the interface __call__ operator.

The adapt method is responsible for adapting an object to the reciever.

The default version returns None:

>>> I.__adapt__(0)

unless the object given provides the interface:

>>> class C(object):
...     zope.interface.implements(I)

>>> obj = C()
>>> I.__adapt__(obj) is obj
True

Adapter hooks can be provided (or removed) to provide custom adaptation. We’ll install a silly hook that adapts 0 to 42. We install a hook by simply adding it to the adapter_hooks list:

>>> from zope.interface.interface import adapter_hooks
>>> def adapt_0_to_42(iface, obj):
...     if obj == 0:
...         return 42

>>> adapter_hooks.append(adapt_0_to_42)
>>> I.__adapt__(0)
42

Hooks must either return an adapter, or None if no adapter can be found.

Hooks can be uninstalled by removing them from the list:

>>> adapter_hooks.remove(adapt_0_to_42)
>>> I.__adapt__(0)

Adapter Registry

Adapter registries provide a way to register objects that depend on one or more interface specifications and provide (perhaps indirectly) some interface. In addition, the registrations have names. (You can think of the names as qualifiers of the provided interfaces.)

The term “interface specification” refers both to interfaces and to interface declarations, such as declarations of interfaces implemented by a class.

Single Adapters

Let’s look at a simple example, using a single required specification:

>>> from zope.interface.adapter import AdapterRegistry
>>> import zope.interface

>>> class IR1(zope.interface.Interface):
...     pass
>>> class IP1(zope.interface.Interface):
...     pass
>>> class IP2(IP1):
...     pass

>>> registry = AdapterRegistry()

We’ll register an object that depends on IR1 and “provides” IP2:

>>> registry.register([IR1], IP2, '', 12)

Given the registration, we can look it up again:

>>> registry.lookup([IR1], IP2, '')
12

Note that we used an integer in the example. In real applications, one would use some objects that actually depend on or provide interfaces. The registry doesn’t care about what gets registered, so we’ll use integers and strings to keep the examples simple. There is one exception. Registering a value of None unregisters any previously-registered value.

If an object depends on a specification, it can be looked up with a specification that extends the specification that it depends on:

>>> class IR2(IR1):
...     pass
>>> registry.lookup([IR2], IP2, '')
12

We can use a class implementation specification to look up the object:

>>> class C2:
...     zope.interface.implements(IR2)

>>> registry.lookup([zope.interface.implementedBy(C2)], IP2, '')
12

and it can be looked up for interfaces that its provided interface extends:

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

But if you require a specification that doesn’t extend the specification the object depends on, you won’t get anything:

>>> registry.lookup([zope.interface.Interface], IP1, '')

By the way, you can pass a default value to lookup:

>>> registry.lookup([zope.interface.Interface], IP1, '', 42)
42

If you try to get an interface the object doesn’t provide, you also won’t get anything:

>>> class IP3(IP2):
...     pass
>>> registry.lookup([IR1], IP3, '')

You also won’t get anything if you use the wrong name:

>>> registry.lookup([IR1], IP1, 'bob')
>>> registry.register([IR1], IP2, 'bob', "Bob's 12")
>>> registry.lookup([IR1], IP1, 'bob')
"Bob's 12"

You can leave the name off when doing a lookup:

>>> registry.lookup([IR1], IP1)
12

If we register an object that provides IP1:

>>> registry.register([IR1], IP1, '', 11)

then that object will be prefered over O(12):

>>> registry.lookup([IR1], IP1, '')
11

Also, if we register an object for IR2, then that will be prefered when using IR2:

>>> registry.register([IR2], IP1, '', 21)
>>> registry.lookup([IR2], IP1, '')
21
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-adapters

You can adapt multiple specifications:

>>> registry.register([IR1, IQ], IP2, '', '1q2')
>>> registry.lookup([IR1, IQ], IP2, '')
'1q2'
>>> registry.lookup([IR2, IQ], IP1, '')
'1q2'

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

>>> class IQ2(IQ):
...     pass

>>> registry.lookup([IR2, IQ2], IP1, '')
'1q2'

>>> registry.register([IR1, IQ2], IP2, '', '1q22')
>>> registry.lookup([IR2, IQ2], IP1, '')
'1q22'
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'

Null Adapters

You can also adapt no specification:

>>> registry.register([], IP2, '', 2)
>>> registry.lookup([], IP2, '')
2
>>> registry.lookup([], IP1, '')
2
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)]

Subscriptions

Normally, we want to look up an object that most-closely matches a specification. Sometimes, we want to get all of the objects that match some specification. We use subscriptions for this. We subscribe objects against specifications and then later find all of the subscribed objects:

>>> registry.subscribe([IR1], IP2, 'sub12 1')
>>> registry.subscriptions([IR1], IP2)
['sub12 1']

Note that, unlike regular adapters, subscriptions are unnamed.

You can have multiple subscribers for the same specification:

>>> registry.subscribe([IR1], IP2, 'sub12 2')
>>> registry.subscriptions([IR1], IP2)
['sub12 1', 'sub12 2']

If subscribers are registered for the same required interfaces, they are returned in the order of definition.

You can register subscribers for all specifications using None:

>>> registry.subscribe([None], IP1, 'sub_1')
>>> registry.subscriptions([IR2], IP1)
['sub_1', 'sub12 1', 'sub12 2']

Note that the new subscriber is returned first. Subscribers defined for more general required interfaces are returned before subscribers for more general interfaces.

Subscriptions may be combined over multiple compatible specifications:

>>> registry.subscriptions([IR2], IP1)
['sub_1', 'sub12 1', 'sub12 2']
>>> registry.subscribe([IR1], IP1, 'sub11')
>>> registry.subscriptions([IR2], IP1)
['sub_1', 'sub12 1', 'sub12 2', 'sub11']
>>> registry.subscribe([IR2], IP2, 'sub22')
>>> registry.subscriptions([IR2], IP1)
['sub_1', 'sub12 1', 'sub12 2', 'sub11', 'sub22']
>>> registry.subscriptions([IR2], IP2)
['sub12 1', 'sub12 2', 'sub22']

Subscriptions can be on multiple specifications:

>>> registry.subscribe([IR1, IQ], IP2, 'sub1q2')
>>> registry.subscriptions([IR1, IQ], IP2)
['sub1q2']

As with single subscriptions and non-subscription adapters, you can specify None for the first required interface, to specify a default:

>>> registry.subscribe([None, IQ], IP2, 'sub_q2')
>>> registry.subscriptions([IS, IQ], IP2)
['sub_q2']
>>> registry.subscriptions([IR1, IQ], IP2)
['sub_q2', 'sub1q2']

You can have subscriptions that are indepenent of any specifications:

>>> list(registry.subscriptions([], IP1))
[]

>>> registry.subscribe([], IP2, 'sub2')
>>> registry.subscriptions([], IP1)
['sub2']
>>> registry.subscribe([], IP1, 'sub1')
>>> registry.subscriptions([], IP1)
['sub2', 'sub1']
>>> registry.subscriptions([], IP2)
['sub2']
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

Using the Adapter Registry

This is a small demonstration of the zope.interface package including its adapter registry. It is intended to provide a concrete but narrow example on how to use interfaces and adapters outside of Zope 3.

First we have to import the interface package.

>>> import zope.interface

We now develop an interface for our object, which is a simple file in this case. For now we simply support one attribute, the body, which contains the actual file contents.

>>> class IFile(zope.interface.Interface):
...
...     body = zope.interface.Attribute('Contents of the file.')
...

For statistical reasons we often want to know the size of a file. However, it would be clumsy to implement the size directly in the file object, since the size really represents meta-data. Thus we create another interface that provides the size of something.

>>> class ISize(zope.interface.Interface):
...
...     def getSize():
...         'Return the size of an object.'
...

Now we need to implement the file. It is essential that the object states that it implements the IFile interface. We also provide a default body value (just to make things simpler for this example).

>>> class File(object):
...
...      zope.interface.implements(IFile)
...      body = 'foo bar'
...

Next we implement an adapter that can provide the ISize interface given any object providing IFile. By convention we use __used_for__ to specify the interface that we expect the adapted object to provide, in our case IFile. However, this attribute is not used for anything. If you have multiple interfaces for which an adapter is used, just specify the interfaces via a tuple.

Again by convention, the constructor of an adapter takes one argument, the context. The context in this case is an instance of File (providing IFile) that is used to extract the size from. Also by convention the context is stored in an attribute named context on the adapter. The twisted community refers to the context as the original object. However, you may feel free to use a specific argument name, such as file.

>>> class FileSize(object):
...
...      zope.interface.implements(ISize)
...      __used_for__ = IFile
...
...      def __init__(self, context):
...          self.context = context
...
...      def getSize(self):
...          return len(self.context.body)
...

Now that we have written our adapter, we have to register it with an adapter registry, so that it can be looked up when needed. There is no such thing as a global registry; thus we have to instantiate one for our example manually.

>>> from zope.interface.adapter import AdapterRegistry
>>> registry = AdapterRegistry()

The registry keeps a map of what adapters implement based on another interface, the object already provides. Therefore, we next have to register an adapter that adapts from IFile to ISize. The first argument to the registry’s register() method is a list of original interfaces.In our cause we have only one original interface, IFile. A list makes sense, since the interface package has the concept of multi-adapters, which are adapters that require multiple objects to adapt to a new interface. In these situations, your adapter constructor will require an argument for each specified interface.

The second argument is the interface the adapter provides, in our case ISize. The third argument is the name of the adapter. Since we do not care about names, we simply leave it as an empty string. Names are commonly useful, if you have adapters for the same set of interfaces, but they are useful in different situations. The last argument is simply the adapter class.

>>> registry.register([IFile], ISize, '', FileSize)

You can now use the the registry to lookup the adapter.

>>> registry.lookup1(IFile, ISize, '')
<class '__main__.FileSize'>

Let’s get a little bit more practical. Let’s create a File instance and create the adapter using a registry lookup. Then we see whether the adapter returns the correct size by calling getSize().

>>> file = File()
>>> size = registry.lookup1(IFile, ISize, '')(file)
>>> size.getSize()
7

However, this is not very practical, since I have to manually pass in the arguments to the lookup method. There is some syntactic candy that will allow us to get an adapter instance by simply calling ISize(file). To make use of this functionality, we need to add our registry to the adapter_hooks list, which is a member of the adapters module. This list stores a collection of callables that are automatically invoked when IFoo(obj) is called; their purpose is to locate adapters that implement an interface for a certain context instance.

You are required to implement your own adapter hook; this example covers one of the simplest hooks that use the registry, but you could implement one that used an adapter cache or persistent adapters, for instance. The helper hook is required to expect as first argument the desired output interface (for us ISize) and as the second argument the context of the adapter (here file). The function returns an adapter, i.e. a FileSize instance.

>>> def hook(provided, object):
...     adapter = registry.lookup1(zope.interface.providedBy(object),
...                                provided, '')
...     return adapter(object)
...

We now just add the hook to an adapter_hooks list.

>>> from zope.interface.interface import adapter_hooks
>>> adapter_hooks.append(hook)

Once the hook is registered, you can use the desired syntax.

>>> size = ISize(file)
>>> size.getSize()
7

Now we have to cleanup after ourselves, so that others after us have a clean adapter_hooks list.

>>> adapter_hooks.remove(hook)

That’s it. I have intentionally left out a discussion of named adapters and multi-adapters, since this text is intended as a practical and simple introduction to Zope 3 interfaces and adapters. You might want to read the adapter.txt in the zope.interface package for a more formal, referencial and complete treatment of the package. Warning: People have reported that adapter.txt makes their brain feel soft!

Download

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

zope.interface-3.3.0.1.tar.gz (105.1 kB view hashes)

Uploaded Source

Built Distributions

zope.interface-3.3.0.1-py2.6-win-amd64.egg (212.2 kB view hashes)

Uploaded Source

zope.interface-3.3.0.1-py2.6-win32.egg (211.4 kB view hashes)

Uploaded Source

zope.interface-3.3.0.1-py2.5-win32.egg (209.6 kB view hashes)

Uploaded Source

zope.interface-3.3.0.1-py2.4-win32.egg (211.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page