Interface Specifications

This document discusses the actual interface objects themselves. We begin with a basic concept of specifying an object’s behaviour (with an ISpecification), and then we describe the way we write such a specification (IInterface). Combinations of specifications (e.g., an object that provides multiple interfaces) are covered by IDeclaration.

Specification

Specification objects implement the API defined by ISpecification:

interface zope.interface.interfaces.ISpecification[source]

Object Behavioral specifications

providedBy(object)

Test whether the interface is implemented by the object

Return true of the object asserts that it implements the interface, including asserting that it implements an extended interface.

implementedBy(class_)

Test whether the interface is implemented by instances of the class

Return true of the class asserts that its instances implement the interface, including asserting that they implement an extended interface.

isOrExtends(other)

Test whether the specification is or extends another

extends(other, strict=True)

Test whether a specification extends another

The specification extends other if it has other as a base interface or if one of it’s bases extends other.

If strict is false, then the specification extends itself.

weakref(callback=None)

Return a weakref to the specification

This method is, regrettably, needed to allow weakrefs to be computed to security-proxied specifications. While the zope.interface package does not require zope.security or zope.proxy, it has to be able to coexist with it.

__bases__

Base specifications

A tuple of specifications from which this specification is directly derived.

__sro__

Specification-resolution order

A tuple of the specification and all of it’s ancestor specifications from most specific to least specific. The specification itself is the first element.

(This is similar to the method-resolution order for new-style classes.)

__iro__

Interface-resolution order

A tuple of the specification’s ancestor interfaces from most specific to least specific. The specification itself is included if it is an interface.

(This is similar to the method-resolution order for new-style classes.)

get(name, default=None)

Look up the description for a name

If the named attribute is not defined, the default is returned.

class zope.interface.interface.Specification(bases=())[source]

Specifications

An interface specification is used to track interface declarations and component registrations.

This class is a base class for both interfaces themselves and for interface specifications (declarations).

Specifications are mutable. If you reassign their bases, their relations with other specifications are adjusted accordingly.

For example:

>>> from zope.interface.interface import Specification
>>> from zope.interface import Interface
>>> class I1(Interface):
...     pass
>>> class I2(I1):
...     pass
>>> class I3(I2):
...     pass
>>> [i.__name__ for i in I1.__bases__]
['Interface']
>>> [i.__name__ for i in I2.__bases__]
['I1']
>>> I3.extends(I1)
True
>>> I2.__bases__ = (Interface, )
>>> [i.__name__ for i in I2.__bases__]
['Interface']
>>> I3.extends(I1)
False

Exmples for Specification.providedBy():

>>> from zope.interface import *
>>> class I1(Interface):
...     pass
>>> @implementer(I1)
... class C(object):
...     pass
>>> c = C()
>>> class X(object):
...     pass
>>> x = X()
>>> I1.providedBy(x)
False
>>> I1.providedBy(C)
False
>>> I1.providedBy(c)
True
>>> directlyProvides(x, I1)
>>> I1.providedBy(x)
True
>>> directlyProvides(C, I1)
>>> I1.providedBy(C)
True

Examples for Specification.isOrExtends():

>>> from zope.interface import Interface
>>> from zope.interface.declarations import Declaration
>>> class I1(Interface): pass
...
>>> class I2(I1): pass
...
>>> class I3(Interface): pass
...
>>> class I4(I3): pass
...
>>> spec = Declaration()
>>> int(spec.extends(Interface))
1
>>> spec = Declaration(I2)
>>> int(spec.extends(Interface))
1
>>> int(spec.extends(I1))
1
>>> int(spec.extends(I2))
1
>>> int(spec.extends(I3))
0
>>> int(spec.extends(I4))
0

Examples for Specification.interfaces():

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(I1): pass
...
>>> class I3(Interface): pass
...
>>> class I4(I3): pass
...
>>> spec = Specification((I2, I3))
>>> spec = Specification((I4, spec))
>>> i = spec.interfaces()
>>> [x.getName() for x in i]
['I4', 'I2', 'I3']
>>> list(i)
[]

Exmples for Specification.extends():

>>> from zope.interface import Interface
>>> from zope.interface.declarations import Declaration
>>> class I1(Interface): pass
...
>>> class I2(I1): pass
...
>>> class I3(Interface): pass
...
>>> class I4(I3): pass
...
>>> spec = Declaration()
>>> int(spec.extends(Interface))
1
>>> spec = Declaration(I2)
>>> int(spec.extends(Interface))
1
>>> int(spec.extends(I1))
1
>>> int(spec.extends(I2))
1
>>> int(spec.extends(I3))
0
>>> int(spec.extends(I4))
0
>>> I2.extends(I2)
False
>>> I2.extends(I2, False)
True
>>> I2.extends(I2, strict=False)
True

Interface

Interfaces are a particular type of ISpecification and implement the API defined by IInterface.

Before we get there, we need to discuss two related concepts. The first is that of an “element”, which provides us a simple way to query for information generically (this is important because we’ll see that IInterface implements this interface):

interface zope.interface.interfaces.IElement[source]

Objects that have basic documentation and tagged values.

Known derivatives include IAttribute and its derivative IMethod; these have no notion of inheritance. IInterface is also a derivative, and it does have a notion of inheritance, expressed through its __bases__ and ordered in its __iro__ (both defined by ISpecification).

class zope.interface.interface.Element(__name__, __doc__='')[source]

Default implementation of zope.interface.interfaces.IElement.

Next, we look at IAttribute and IMethod. These make up the content, or body, of an Interface.

interface zope.interface.interfaces.IAttribute[source]

Extends: zope.interface.interfaces.IElement

Attribute descriptors

class zope.interface.interface.Attribute(__name__, __doc__='')[source]

Attribute descriptions

interface zope.interface.interfaces.IMethod[source]

Extends: zope.interface.interfaces.IAttribute

Method attributes

class zope.interface.interface.Method(__name__, __doc__='')[source]

Method interfaces

The idea here is that you have objects that describe methods. This provides an opportunity for rich meta-data.

Finally we can look at the definition of IInterface.

interface zope.interface.interfaces.IInterface[source]

Extends: zope.interface.interfaces.ISpecification, zope.interface.interfaces.IElement

Interface objects

Interface objects describe the behavior of an object by containing useful information about the object. This information includes:

  • Prose documentation about the object. In Python terms, this is called the “doc string” of the interface. In this element, you describe how the object works in prose language and any other useful information about the object.

  • Descriptions of attributes. Attribute descriptions include the name of the attribute and prose documentation describing the attributes usage.

  • Descriptions of methods. Method descriptions can include:

    • Prose “doc string” documentation about the method and its usage.

    • A description of the methods arguments; how many arguments are expected, optional arguments and their default values, the position or arguments in the signature, whether the method accepts arbitrary arguments and whether the method accepts arbitrary keyword arguments.

  • Optional tagged data. Interface objects (and their attributes and methods) can have optional, application specific tagged data associated with them. Examples uses for this are examples, security assertions, pre/post conditions, and other possible information you may want to associate with an Interface or its attributes.

Not all of this information is mandatory. For example, you may only want the methods of your interface to have prose documentation and not describe the arguments of the method in exact detail. Interface objects are flexible and let you give or take any of these components.

Interfaces are created with the Python class statement using either zope.interface.Interface or another interface, as in:

 from zope.interface import Interface

 class IMyInterface(Interface):
   '''Interface documentation'''

   def meth(arg1, arg2):
       '''Documentation for meth'''

   # Note that there is no self argument

class IMySubInterface(IMyInterface):
   '''Interface documentation'''

   def meth2():
       '''Documentation for meth2'''

You use interfaces in two ways:

  • You assert that your object implement the interfaces.

    There are several ways that you can declare that an object provides an interface:

    1. Call zope.interface.implementer on your class definition.

    2. Call zope.interface.directlyProvides on your object.

    3. Call zope.interface.classImplements to declare that instances of a class implement an interface.

      For example:

      from zope.interface import classImplements

classImplements(some_class, some_interface)

      This approach is useful when it is not an option to modify the class source. Note that this doesn’t affect what the class itself implements, but only what its instances implement.

  • You query interface meta-data. See the IInterface methods and attributes for details.

interface zope.interface.Interface

Usage

Exmples for InterfaceClass.extends():

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>>
>>> i = I1.interfaces()
>>> [x.getName() for x in i]
['I1']
>>> list(i)
[]