zope.interface API Documentation

zope.interface.interface.Specification

API

Specification objects implement the API defined by zope.interface.interfaces.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 if 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.

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

__iro__

Interface-resolution order

A tuple of the 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.

Usage

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
>>> class C(object):
...     implements(I1)
>>> 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

zope.interface.interface.InterfaceClass

API

Specification objects implement the API defined by zope.interface.interfaces.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:

o 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.
o Descriptions of attributes. Attribute descriptions include
the name of the attribute and prose documentation describing the attributes usage.

o 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.
o 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 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:

o You assert that your object implement the interfaces.

There are several ways that you can assert that an object implements an interface:

  1. Call zope.interface.implements in your class definition.

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

  3. Call ‘zope.interface.classImplements’ to assert 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.

o You query interface meta-data. See the IInterface methods and
attributes for details.
names(all=False)

Get the interface attribute names

Return a sequence of the names of the attributes, including methods, included in the interface definition.

Normally, only directly defined attributes are included. If a true positional or keyword argument is given, then attributes defined by base classes will be included.

namesAndDescriptions(all=False)

Get the interface attribute names and descriptions

Return a sequence of the names and descriptions of the attributes, including methods, as name-value pairs, included in the interface definition.

Normally, only directly defined attributes are included. If a true positional or keyword argument is given, then attributes defined by base classes will be included.

__getitem__(name)

Get the description for a name

If the named attribute is not defined, a KeyError is raised.

direct(name)

Get the description for the name if it was defined by the interface

If the interface doesn’t define the name, returns None.

validateInvariants(obj, errors=None)

Validate invariants

Validate object to defined invariants. If errors is None, raises first Invalid error; if errors is a list, appends all errors to list, then raises Invalid with the errors as the first element of the “args” tuple.

__contains__(name)

Test whether the name is defined by the interface

__iter__()

Return an iterator over the names defined by the interface

The names iterated include all of the names defined by the interface directly and indirectly by base interfaces.

__module__

The name of the module defining the 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)
[]

zope.interface.declarations.Declaration

API

Specification objects implement the API defined by zope.interface.interfaces.IDeclaration:

interface zope.interface.interfaces.IDeclaration[source]

Extends: zope.interface.interfaces.ISpecification

Interface declaration

Declarations are used to express the interfaces implemented by classes or provided by objects.

__contains__(interface)

Test whether an interface is in the specification

Return true if the given interface is one of the interfaces in the specification and false otherwise.

__iter__()

Return an iterator for the interfaces in the specification

flattened()

Return an iterator of all included and extended interfaces

An iterator is returned for all interfaces either included in or extended by interfaces included in the specifications without duplicates. The interfaces are in “interface resolution order”. The interface resolution order is such that base interfaces are listed after interfaces that extend them and, otherwise, interfaces are included in the order that they were defined in the specification.

__sub__(interfaces)

Create an interface specification with some interfaces excluded

The argument can be an interface or an interface specifications. The interface or interfaces given in a specification are subtracted from the interface specification.

Removing an interface that is not in the specification does not raise an error. Doing so has no effect.

Removing an interface also removes sub-interfaces of the interface.

__add__(interfaces)

Create an interface specification with some interfaces added

The argument can be an interface or an interface specifications. The interface or interfaces given in a specification are added to the interface specification.

Adding an interface that is already in the specification does not raise an error. Doing so has no effect.

__nonzero__()

Return a true value of the interface specification is non-empty

Usage

Exmples for Declaration.__contains__():

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

Exmples for Declaration.__iter__():

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

Exmples for Declaration.flattened():

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

Exmples for Declaration.__sub__():

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(I1): pass
...
>>> class I3(Interface): pass
...
>>> class I4(I3): pass
...
>>> spec = Declaration()
>>> [iface.getName() for iface in spec]
[]
>>> spec -= I1
>>> [iface.getName() for iface in spec]
[]
>>> spec -= Declaration(I1, I2)
>>> [iface.getName() for iface in spec]
[]
>>> spec = Declaration(I2, I4)
>>> [iface.getName() for iface in spec]
['I2', 'I4']
>>> [iface.getName() for iface in spec - I4]
['I2']
>>> [iface.getName() for iface in spec - I1]
['I4']
>>> [iface.getName() for iface
...  in spec - Declaration(I3, I4)]
['I2']

Exmples for Declaration.__add__():

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(I1): pass
...
>>> class I3(Interface): pass
...
>>> class I4(I3): pass
...
>>> spec = Declaration()
>>> [iface.getName() for iface in spec]
[]
>>> [iface.getName() for iface in spec+I1]
['I1']
>>> [iface.getName() for iface in I1+spec]
['I1']
>>> spec2 = spec
>>> spec += I1
>>> [iface.getName() for iface in spec]
['I1']
>>> [iface.getName() for iface in spec2]
[]
>>> spec2 += Declaration(I3, I4)
>>> [iface.getName() for iface in spec2]
['I3', 'I4']
>>> [iface.getName() for iface in spec+spec2]
['I1', 'I3', 'I4']
>>> [iface.getName() for iface in spec2+spec]
['I3', 'I4', 'I1']

zope.interface.declarations.implementedBy()

API

zope.interface.declarations.implementedByFallback(cls)[source]

Return the interfaces implemented for a class’ instances

The value returned is an IDeclaration.

Usage

Consider the following example:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
...
>>> class I3(Interface): pass
...
>>> class I4(Interface): pass
...
>>> class A(object):
...   implements(I3)
>>> class B(object):
...   implements(I4)
>>> class C(A, B):
...   pass
>>> classImplementsOnly(C, I1, I2)
>>> [i.getName() for i in implementedBy(C)]
['I1', 'I2']

Instances of C provide only I1, I2, and regardless of whatever interfaces instances of A and B implement.

Another example:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(I1): pass
...
>>> class I3(Interface): pass
...
>>> class I4(I3): pass
...
>>> class C1(object):
...   implements(I2)
>>> class C2(C1):
...   implements(I3)
>>> [i.getName() for i in implementedBy(C2)]
['I3', 'I2']

Really, any object should be able to receive a successful answer, even an instance:

>>> class Callable(object):
...     def __call__(self):
...         return self
>>> implementedBy(Callable())
<implementedBy __builtin__.?>

Note that the name of the spec ends with a ‘?’, because the Callable instance does not have a __name__ attribute.

This also manages storage of implementation specifications.

zope.interface.declarations.classImplementsOnly()

API

zope.interface.declarations.classImplementsOnly(cls, *interfaces)[source]

Declare the only interfaces implemented by instances of a class

The arguments after the class are one or more interfaces or interface specifications (IDeclaration objects).

The interfaces given (including the interfaces in the specifications) replace any previous declarations.

Usage

Consider the following example:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
...
>>> class I3(Interface): pass
...
>>> class I4(Interface): pass
...
>>> class A(object):
...   implements(I3)
>>> class B(object):
...   implements(I4)
>>> class C(A, B):
...   pass
>>> classImplementsOnly(C, I1, I2)
>>> [i.getName() for i in implementedBy(C)]
['I1', 'I2']

Instances of C provide only I1, I2, and regardless of whatever interfaces instances of A and B implement.

zope.interface.declarations.classImplements()

API

zope.interface.declarations.classImplements(cls, *interfaces)[source]

Declare additional interfaces implemented for instances of a class

The arguments after the class are one or more interfaces or interface specifications (IDeclaration objects).

The interfaces given (including the interfaces in the specifications) are added to any interfaces previously declared.

Usage

Consider the following example:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
...
>>> class I3(Interface): pass
...
>>> class I4(Interface): pass
...
>>> class I5(Interface): pass
...
>>> class A(object):
...   implements(I3)
>>> class B(object):
...   implements(I4)
>>> class C(A, B):
...   pass
>>> classImplements(C, I1, I2)
>>> [i.getName() for i in implementedBy(C)]
['I1', 'I2', 'I3', 'I4']
>>> classImplements(C, I5)
>>> [i.getName() for i in implementedBy(C)]
['I1', 'I2', 'I5', 'I3', 'I4']

Instances of C provide I1, I2, I5, and whatever interfaces instances of A and B provide.

zope.interface.declarations.implementer

API

class zope.interface.declarations.implementer(*interfaces)[source]

Declare the interfaces implemented by instances of a class.

This function is called as a class decorator.

The arguments are one or more interfaces or interface specifications (IDeclaration objects).

The interfaces given (including the interfaces in the specifications) are added to any interfaces previously declared.

Previous declarations include declarations for base classes unless implementsOnly was used.

This function is provided for convenience. It provides a more convenient way to call classImplements. For example:

@implementer(I1)
class C(object):
    pass

is equivalent to calling:

classImplements(C, I1)

after the class has been created.

zope.interface.declarations.implementer_only

API

class zope.interface.declarations.implementer_only(*interfaces)[source]

Declare the only interfaces implemented by instances of a class

This function is called as a class decorator.

The arguments are one or more interfaces or interface specifications (IDeclaration objects).

Previous declarations including declarations for base classes are overridden.

This function is provided for convenience. It provides a more convenient way to call classImplementsOnly. For example:

@implementer_only(I1)
class C(object): pass

is equivalent to calling:

classImplementsOnly(I1)

after the class has been created.

zope.interface.declarations.implements()

API

zope.interface.declarations.implements(*interfaces)[source]

Declare interfaces implemented by instances of a class

This function is called in a class definition.

The arguments are one or more interfaces or interface specifications (IDeclaration objects).

The interfaces given (including the interfaces in the specifications) are added to any interfaces previously declared.

Previous declarations include declarations for base classes unless implementsOnly was used.

This function is provided for convenience. It provides a more convenient way to call classImplements. For example:

implements(I1)

is equivalent to calling:

classImplements(C, I1)

after the class has been created.

zope.interface.declarations.implementsOnly()

API

zope.interface.declarations.implementsOnly(*interfaces)[source]

Declare the only interfaces implemented by instances of a class

This function is called in a class definition.

The arguments are one or more interfaces or interface specifications (IDeclaration objects).

Previous declarations including declarations for base classes are overridden.

This function is provided for convenience. It provides a more convenient way to call classImplementsOnly. For example:

implementsOnly(I1)

is equivalent to calling:

classImplementsOnly(I1)

after the class has been created.

zope.interface.declarations.ProvidesClass

API

zope.interface.declarations.ProvidesClass

alias of Provides

Usage

Descriptor semantics (via Provides.__get__):

>>> from zope.interface import Interface
>>> class IFooFactory(Interface): pass
...
>>> class C(object):
...   pass
>>> from zope.interface.declarations import ProvidesClass
>>> C.__provides__ = ProvidesClass(C, IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']
>>> getattr(C(), '__provides__', 0)
0

zope.interface.declarations.Provides()

API

zope.interface.declarations.Provides(*interfaces)[source]

Cache instance declarations

Instance declarations are shared among instances that have the same declaration. The declarations are cached in a weak value dictionary.

Usage

In the examples below, we are going to make assertions about the size of the weakvalue dictionary. For the assertions to be meaningful, we need to force garbage collection to make sure garbage objects are, indeed, removed from the system. Depending on how Python is run, we may need to make multiple calls to be sure. We provide a collect function to help with this:

>>> import gc
>>> def collect():
...     for i in range(4):
...         gc.collect()
>>> collect()
>>> from zope.interface.declarations import InstanceDeclarations
>>> before = len(InstanceDeclarations)
>>> class C(object):
...    pass
>>> from zope.interface import Interface
>>> class I(Interface):
...    pass
>>> c1 = C()
>>> c2 = C()
>>> len(InstanceDeclarations) == before
True
>>> directlyProvides(c1, I)
>>> len(InstanceDeclarations) == before + 1
True
>>> directlyProvides(c2, I)
>>> len(InstanceDeclarations) == before + 1
True
>>> del c1
>>> collect()
>>> len(InstanceDeclarations) == before + 1
True
>>> del c2
>>> collect()
>>> len(InstanceDeclarations) == before
True

zope.interface.declarations.directlyProvides()

API

zope.interface.declarations.directlyProvides(object, *interfaces)[source]

Declare interfaces declared directly for an object

The arguments after the object are one or more interfaces or interface specifications (IDeclaration objects).

The interfaces given (including the interfaces in the specifications) replace interfaces previously declared for the object.

Usage

Consider the following example:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
...
>>> class IA1(Interface): pass
...
>>> class IA2(Interface): pass
...
>>> class IB(Interface): pass
...
>>> class IC(Interface): pass
...
>>> class A(object):
...     implements(IA1, IA2)
>>> class B(object):
...     implements(IB)
>>> class C(A, B):
...    implements(IC)
>>> ob = C()
>>> directlyProvides(ob, I1, I2)
>>> int(I1 in providedBy(ob))
1
>>> int(I2 in providedBy(ob))
1
>>> int(IA1 in providedBy(ob))
1
>>> int(IA2 in providedBy(ob))
1
>>> int(IB in providedBy(ob))
1
>>> int(IC in providedBy(ob))
1

The object, ob provides I1, I2, and whatever interfaces instances have been declared for instances of C.

To remove directly provided interfaces, use directlyProvidedBy and subtract the unwanted interfaces. For example:

>>> directlyProvides(ob, directlyProvidedBy(ob)-I2)
>>> int(I1 in providedBy(ob))
1
>>> int(I2 in providedBy(ob))
0

removes I2 from the interfaces directly provided by ob. The object, ob no longer directly provides I2, although it might still provide I2 if its class implements I2.

To add directly provided interfaces, use directlyProvidedBy and include additional interfaces. For example:

>>> int(I2 in providedBy(ob))
0
>>> directlyProvides(ob, directlyProvidedBy(ob), I2)

adds I2 to the interfaces directly provided by ob:

>>> int(I2 in providedBy(ob))
1

We need to avoid setting this attribute on meta classes that don’t support descriptors.

We can do away with this check when we get rid of the old EC

zope.interface.declarations.alsoProvides()

API

zope.interface.declarations.alsoProvides(object, *interfaces)[source]

Declare interfaces declared directly for an object

The arguments after the object are one or more interfaces or interface specifications (IDeclaration objects).

The interfaces given (including the interfaces in the specifications) are added to the interfaces previously declared for the object.

Usage

Consider the following example:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
...
>>> class IA1(Interface): pass
...
>>> class IA2(Interface): pass
...
>>> class IB(Interface): pass
...
>>> class IC(Interface): pass
...
>>> class A(object):
...     implements(IA1, IA2)
>>> class B(object):
...     implements(IB)
>>> class C(A, B):
...    implements(IC)
>>> ob = C()
>>> directlyProvides(ob, I1)
>>> int(I1 in providedBy(ob))
1
>>> int(I2 in providedBy(ob))
0
>>> int(IA1 in providedBy(ob))
1
>>> int(IA2 in providedBy(ob))
1
>>> int(IB in providedBy(ob))
1
>>> int(IC in providedBy(ob))
1
>>> alsoProvides(ob, I2)
>>> int(I1 in providedBy(ob))
1
>>> int(I2 in providedBy(ob))
1
>>> int(IA1 in providedBy(ob))
1
>>> int(IA2 in providedBy(ob))
1
>>> int(IB in providedBy(ob))
1
>>> int(IC in providedBy(ob))
1

The object, ob provides I1, I2, and whatever interfaces instances have been declared for instances of C. Notice that the alsoProvides just extends the provided interfaces.

zope.interface.declarations.noLongerProvides()

API

zope.interface.declarations.noLongerProvides(object, interface)[source]

Removes a directly provided interface from an object.

Usage

Consider the following two interfaces:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
...

I1 is provided through the class, I2 is directly provided by the object:

>>> class C(object):
...    implements(I1)
>>> c = C()
>>> alsoProvides(c, I2)
>>> I2.providedBy(c)
True

Remove I2 from c again:

>>> noLongerProvides(c, I2)
>>> I2.providedBy(c)
False

Removing an interface that is provided through the class is not possible:

>>> noLongerProvides(c, I1)
Traceback (most recent call last):
...
ValueError: Can only remove directly provided interfaces.

zope.interface.declarations.directlyProvidedBy()

API

zope.interface.declarations.directlyProvidedBy(object)[source]

Return the interfaces directly provided by the given object

The value returned is an IDeclaration.

zope.interface.declarations.classProvides()

API

zope.interface.declarations.classProvides(*interfaces)[source]

Declare interfaces provided directly by a class

This function is called in a class definition.

The arguments are one or more interfaces or interface specifications (IDeclaration objects).

The given interfaces (including the interfaces in the specifications) are used to create the class’s direct-object interface specification. An error will be raised if the module class has an direct interface specification. In other words, it is an error to call this function more than once in a class definition.

Note that the given interfaces have nothing to do with the interfaces implemented by instances of the class.

This function is provided for convenience. It provides a more convenient way to call directlyProvides for a class. For example:

classProvides(I1)

is equivalent to calling:

directlyProvides(theclass, I1)

after the class has been created.

Usage

For example:

>>> from zope.interface import Interface
>>> from zope.interface.declarations import implementer
>>> class IFooFactory(Interface):
...     pass
>>> class IFoo(Interface):
...     pass
>>> @implementer(IFoo)
... class C(object):
...     classProvides(IFooFactory)
>>> [i.getName() for i in C.__provides__]
['IFooFactory']
>>> [i.getName() for i in C().__provides__]
['IFoo']

Which is equivalent to:

>>> from zope.interface import Interface
>>> class IFoo(Interface): pass
...
>>> class IFooFactory(Interface): pass
...
>>> @implementer(IFoo)
... class C(object):
...   pass
>>> directlyProvides(C, IFooFactory)
>>> [i.getName() for i in C.__providedBy__]
['IFooFactory']
>>> [i.getName() for i in C().__providedBy__]
['IFoo']

zope.interface.declarations.provider

API

class zope.interface.declarations.provider(*interfaces)[source]

Class decorator version of classProvides

zope.interface.declarations.moduleProvides()

API

zope.interface.declarations.moduleProvides(*interfaces)[source]

Declare interfaces provided by a module

This function is used in a module definition.

The arguments are one or more interfaces or interface specifications (IDeclaration objects).

The given interfaces (including the interfaces in the specifications) are used to create the module’s direct-object interface specification. An error will be raised if the module already has an interface specification. In other words, it is an error to call this function more than once in a module definition.

This function is provided for convenience. It provides a more convenient way to call directlyProvides. For example:

moduleImplements(I1)

is equivalent to:

directlyProvides(sys.modules[__name__], I1)

zope.interface.declarations.ObjectSpecification()

API

zope.interface.declarations.ObjectSpecification(direct, cls)[source]

Provide object specifications

These combine information for the object and for it’s classes.

Usage

For example:

>>> from zope.interface import Interface
>>> class I1(Interface): pass
...
>>> class I2(Interface): pass
...
>>> class I3(Interface): pass
...
>>> class I31(I3): pass
...
>>> class I4(Interface): pass
...
>>> class I5(Interface): pass
...
>>> class A(object):
...     implements(I1)
>>> class B(object): __implemented__ = I2
...
>>> class C(A, B):
...     implements(I31)
>>> c = C()
>>> directlyProvides(c, I4)
>>> [i.getName() for i in providedBy(c)]
['I4', 'I31', 'I1', 'I2']
>>> [i.getName() for i in providedBy(c).flattened()]
['I4', 'I31', 'I3', 'I1', 'I2', 'Interface']
>>> int(I1 in providedBy(c))
1
>>> int(I3 in providedBy(c))
0
>>> int(providedBy(c).extends(I3))
1
>>> int(providedBy(c).extends(I31))
1
>>> int(providedBy(c).extends(I5))
0
>>> class COnly(A, B):
...     implementsOnly(I31)
>>> class D(COnly):
...     implements(I5)
>>> c = D()
>>> directlyProvides(c, I4)
>>> [i.getName() for i in providedBy(c)]
['I4', 'I5', 'I31']
>>> [i.getName() for i in providedBy(c).flattened()]
['I4', 'I5', 'I31', 'I3', 'Interface']
>>> int(I1 in providedBy(c))
0
>>> int(I3 in providedBy(c))
0
>>> int(providedBy(c).extends(I3))
1
>>> int(providedBy(c).extends(I1))
0
>>> int(providedBy(c).extends(I31))
1
>>> int(providedBy(c).extends(I5))
1

zope.interface.declarations.providedBy()

API

zope.interface.declarations.providedBy()

Get an object’s interfaces

zope.interface.declarations.ObjectSpecificationDescriptor

API

class zope.interface.declarations.ObjectSpecificationDescriptor

Object Specification Descriptor

Usage

For example:

>>> from zope.interface import Interface
>>> class IFoo(Interface): pass
...
>>> class IFooFactory(Interface): pass
...
>>> @implementer(IFoo)
... class C(object):
...   classProvides(IFooFactory)
>>> [i.getName() for i in C.__providedBy__]
['IFooFactory']
>>> [i.getName() for i in C().__providedBy__]
['IFoo']

Get an ObjectSpecification bound to either an instance or a class, depending on how we were accessed.

zope.interface.declarations.named

API

class zope.interface.declarations.named(name)[source]

Usage

For example:

>>> from zope.interface.declarations import named

>>> @named('foo')
... class Foo(object):
...     pass

>>> Foo.__component_name__
'foo'

When registering an adapter or utility component, the registry looks for the __component_name__ attribute and uses it, if no name was explicitly provided.

zope.interface.adapter.AdapterRegistry

API

The adapter registry’s API is defined by zope.interface.interfaces.IAdapterRegistry:

interface zope.interface.adapter.IAdapterRegistry[source]

Provide an interface-based registry for adapters

This registry registers objects that are in some sense “from” a sequence of specification to an interface and a name.

No specific semantics are assumed for the registered objects, however, the most common application will be to register factories that adapt objects providing required specifications to a provided interface.

register(required, provided, name, value)

Register a value

A value is registered for a sequence of required specifications, a provided interface, and a name.

registered(required, provided, name=u'')

Return the component registered for the given interfaces and name

Unlike the lookup method, this methods won’t retrieve components registered for more specific required interfaces or less specific provided interfaces.

If no component was registered exactly for the given interfaces and name, then None is returned.

lookup(required, provided, name='', default=None)

Lookup a value

A value is looked up based on a sequence of required specifications, a provided interface, and a name.

queryMultiAdapter(objects, provided, name=u'', default=None)

Adapt a sequence of objects to a named, provided, interface

lookup1(required, provided, name=u'', default=None)

Lookup a value using a single required interface

A value is looked up based on a single required specifications, a provided interface, and a name.

queryAdapter(object, provided, name=u'', default=None)

Adapt an object using a registered adapter factory.

adapter_hook(provided, object, name=u'', default=None)

Adapt an object using a registered adapter factory.

lookupAll(required, provided)

Find all adapters from the required to the provided interfaces

An iterable object is returned that provides name-value two-tuples.

names(required, provided)

Return the names for which there are registered objects

subscribe(required, provided, subscriber, name=u'')

Register a subscriber

A subscriber is registered for a sequence of required specifications, a provided interface, and a name.

Multiple subscribers may be registered for the same (or equivalent) interfaces.

subscriptions(required, provided, name=u'')

Get a sequence of subscribers

Subscribers for a sequence of required interfaces, and a provided interface are returned.

subscribers(objects, provided, name=u'')

Get a sequence of subscription adapters

Usage

See Adapter Registry.

zope.interface.registry.Components

API

The component registry’s API is defined by zope.interface.interfaces.IComponents:

interface zope.interface.interfaces.IComponents[source]

Extends: zope.interface.interfaces.IComponentLookup, zope.interface.interfaces.IComponentRegistry

Component registration and access

interface zope.interface.interfaces.IComponentLookup[source]

Component Manager for a Site

This object manages the components registered at a particular site. The definition of a site is intentionally vague.

adapters

Adapter Registry to manage all registered adapters.

utilities

Adapter Registry to manage all registered utilities.

queryAdapter(object, interface, name=u'', default=None)

Look for a named adapter to an interface for an object

If a matching adapter cannot be found, returns the default.

getAdapter(object, interface, name=u'')

Look for a named adapter to an interface for an object

If a matching adapter cannot be found, a ComponentLookupError is raised.

queryMultiAdapter(objects, interface, name=u'', default=None)

Look for a multi-adapter to an interface for multiple objects

If a matching adapter cannot be found, returns the default.

getMultiAdapter(objects, interface, name=u'')

Look for a multi-adapter to an interface for multiple objects

If a matching adapter cannot be found, a ComponentLookupError is raised.

getAdapters(objects, provided)

Look for all matching adapters to a provided interface for objects

Return an iterable of name-adapter pairs for adapters that provide the given interface.

subscribers(objects, provided)

Get subscribers

Subscribers are returned that provide the provided interface and that depend on and are comuted from the sequence of required objects.

handle(*objects)

Call handlers for the given objects

Handlers registered for the given objects are called.

queryUtility(interface, name='', default=None)

Look up a utility that provides an interface.

If one is not found, returns default.

getUtilitiesFor(interface)

Look up the registered utilities that provide an interface.

Returns an iterable of name-utility pairs.

getAllUtilitiesRegisteredFor(interface)

Return all registered utilities for an interface

This includes overridden utilities.

An iterable of utility instances is returned. No names are returned.

interface zope.interface.interfaces.IComponentRegistry[source]

Register components

registerUtility(component=None, provided=None, name=u'', info=u'', factory=None)

Register a utility

factory
Factory for the component to be registerd.
component
The registered component
provided
This is the interface provided by the utility. If the component provides a single interface, then this argument is optional and the component-implemented interface will be used.
name
The utility name.
info
An object that can be converted to a string to provide information about the registration.

Only one of component and factory can be used. A Registered event is generated with an IUtilityRegistration.

unregisterUtility(component=None, provided=None, name=u'', factory=None)

Unregister a utility

A boolean is returned indicating whether the registry was changed. If the given component is None and there is no component registered, or if the given component is not None and is not registered, then the function returns False, otherwise it returns True.

factory
Factory for the component to be unregisterd.
component
The registered component The given component can be None, in which case any component registered to provide the given provided interface with the given name is unregistered.
provided
This is the interface provided by the utility. If the component is not None and provides a single interface, then this argument is optional and the component-implemented interface will be used.
name
The utility name.

Only one of component and factory can be used. An UnRegistered event is generated with an IUtilityRegistration.

registeredUtilities()

Return an iterable of IUtilityRegistration instances.

These registrations describe the current utility registrations in the object.

registerAdapter(factory, required=None, provided=None, name=u'', info=u'')

Register an adapter factory

Parameters:

factory
The object used to compute the adapter
required
This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s __component_adapts__ attribute will be used. The __component_adapts__ attribute is usually attribute is normally set in class definitions using adapts function, or for callables using the adapter decorator. If the factory doesn’t have a __component_adapts__ adapts attribute, then this argument is required.
provided
This is the interface provided by the adapter and implemented by the factory. If the factory implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name
The adapter name.
info
An object that can be converted to a string to provide information about the registration.

A Registered event is generated with an IAdapterRegistration.

unregisterAdapter(factory=None, required=None, provided=None, name=u'')

Unregister an adapter factory

A boolean is returned indicating whether the registry was changed. If the given component is None and there is no component registered, or if the given component is not None and is not registered, then the function returns False, otherwise it returns True.

Parameters:

factory
This is the object used to compute the adapter. The factory can be None, in which case any factory registered to implement the given provided interface for the given required specifications with the given name is unregistered.
required
This is a sequence of specifications for objects to be adapted. If the factory is not None and the required arguments is omitted, then the value of the factory’s __component_adapts__ attribute will be used. The __component_adapts__ attribute attribute is normally set in class definitions using adapts function, or for callables using the adapter decorator. If the factory is None or doesn’t have a __component_adapts__ adapts attribute, then this argument is required.
provided
This is the interface provided by the adapter and implemented by the factory. If the factory is not None and implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name
The adapter name.

An Unregistered event is generated with an IAdapterRegistration.

registeredAdapters()

Return an iterable of IAdapterRegistration instances.

These registrations describe the current adapter registrations in the object.

registerSubscriptionAdapter(factory, required=None, provides=None, name=u'', info='')

Register a subscriber factory

Parameters:

factory
The object used to compute the adapter
required
This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s __component_adapts__ attribute will be used. The __component_adapts__ attribute is usually attribute is normally set in class definitions using adapts function, or for callables using the adapter decorator. If the factory doesn’t have a __component_adapts__ adapts attribute, then this argument is required.
provided
This is the interface provided by the adapter and implemented by the factory. If the factory implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name

The adapter name.

Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named subscribers is added.

info
An object that can be converted to a string to provide information about the registration.

A Registered event is generated with an ISubscriptionAdapterRegistration.

unregisterSubscriptionAdapter(factory=None, required=None, provides=None, name=u'')

Unregister a subscriber factory.

A boolean is returned indicating whether the registry was changed. If the given component is None and there is no component registered, or if the given component is not None and is not registered, then the function returns False, otherwise it returns True.

Parameters:

factory
This is the object used to compute the adapter. The factory can be None, in which case any factories registered to implement the given provided interface for the given required specifications with the given name are unregistered.
required
This is a sequence of specifications for objects to be adapted. If the factory is not None and the required arguments is omitted, then the value of the factory’s __component_adapts__ attribute will be used. The __component_adapts__ attribute attribute is normally set in class definitions using adapts function, or for callables using the adapter decorator. If the factory is None or doesn’t have a __component_adapts__ adapts attribute, then this argument is required.
provided
This is the interface provided by the adapter and implemented by the factory. If the factory is not None implements a single interface, then this argument is optional and the factory-implemented interface will be used.
name

The adapter name.

Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named subscribers is added.

An Unregistered event is generated with an ISubscriptionAdapterRegistration.

registeredSubscriptionAdapters()

Return an iterable of ISubscriptionAdapterRegistration instances.

These registrations describe the current subscription adapter registrations in the object.

registerHandler(handler, required=None, name=u'', info='')

Register a handler.

A handler is a subscriber that doesn’t compute an adapter but performs some function when called.

Parameters:

handler
The object used to handle some event represented by the objects passed to it.
required
This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s __component_adapts__ attribute will be used. The __component_adapts__ attribute is usually attribute is normally set in class definitions using adapts function, or for callables using the adapter decorator. If the factory doesn’t have a __component_adapts__ adapts attribute, then this argument is required.
name

The handler name.

Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named handlers is added.

info
An object that can be converted to a string to provide information about the registration.

A Registered event is generated with an IHandlerRegistration.

unregisterHandler(handler=None, required=None, name=u'')

Unregister a handler.

A handler is a subscriber that doesn’t compute an adapter but performs some function when called.

A boolean is returned indicating whether the registry was changed.

Parameters:

handler
This is the object used to handle some event represented by the objects passed to it. The handler can be None, in which case any handlers registered for the given required specifications with the given are unregistered.
required
This is a sequence of specifications for objects to be adapted. If omitted, then the value of the factory’s __component_adapts__ attribute will be used. The __component_adapts__ attribute is usually attribute is normally set in class definitions using adapts function, or for callables using the adapter decorator. If the factory doesn’t have a __component_adapts__ adapts attribute, then this argument is required.
name

The handler name.

Currently, only the empty string is accepted. Other strings will be accepted in the future when support for named handlers is added.

An Unregistered event is generated with an IHandlerRegistration.

registeredHandlers()

Return an iterable of IHandlerRegistration instances.

These registrations describe the current handler registrations in the object.