Verifying interface implementations

The zope.interface.verify module provides functions that test whether a given interface is implemented by a class or provided by an object.

Verifying objects

zope.interface.verify.verifyObject(iface, candidate, tentative=False)

Verify that candidate might correctly provide iface.

This involves:

• Making sure the candidate claims that it provides the interface using iface.providedBy (unless tentative is True, in which case this step is skipped). This means that the candidate’s class declares that it implements the interface, or the candidate itself declares that it provides the interface

• Making sure the candidate defines all the necessary methods

• Making sure the methods have the correct signature (to the extent possible)

• Making sure the candidate defines all the necessary attributes

Return bool:

Returns a true value if everything that could be checked passed.

Raises:

zope.interface.Invalid – If any of the previous conditions does not hold.

Changed in version 5.0: If multiple methods or attributes are invalid, all such errors are collected and reported. Previously, only the first error was reported. As a special case, if only one such error is present, it is raised alone, like before.

exception zope.interface.Invalid

Bases: Exception

A specification is violated

Let’s demonstrate. We’ll begin by defining a simple interface hierarchy requiring two attributes, and a helper method that will instantiate and verify that an object provides this interface.

>>> from zope.interface import Interface, Attribute, implementer
>>> from zope.interface import Invalid
>>> from zope.interface.verify import verifyObject
>>> oname, __name__ = __name__, 'base' # Pretend we're in a module, not a doctest
>>> class IBase(Interface):
...     x = Attribute("The X attribute")
>>> __name__ = 'module' # Pretend to be a different module.
>>> class IFoo(IBase):
...     y = Attribute("The Y attribute")
>>> __name__ = oname; del oname
>>> class Foo(object):
...     pass
>>> def verify_foo(**kwargs):
...    foo = Foo()
...    try:
...        return verifyObject(IFoo, foo, **kwargs)
...    except Invalid as e:
...        print(e)

If we try to verify an instance of this Foo class, three errors will be reported. The declarations (does the object provide IFoo) are checked, as are the attributes specified in the interface being validated (and its ancestors). Notice that the interface being verified is shown, as is the interface where the attribute was defined.

>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo:
    Does not declaratively implement the interface
    The base.IBase.x attribute was not provided
    The module.IFoo.y attribute was not provided

If we add the two missing attributes, we still have the error about not declaring the correct interface.

>>> Foo.x = Foo.y = 42
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: Does not declaratively implement the interface.

If we want to only check the structure of the object, without examining its declarations, we can use the tentative argument.

>>> verify_foo(tentative=True)
True

Of course, we can always mark a particular instance as providing the desired interface.

>>> from zope.interface import alsoProvides
>>> foo = Foo()
>>> alsoProvides(foo, IFoo)
>>> verifyObject(IFoo, foo)
True

If all instances will provide the interface, we can mark a class as implementing it. But we have to remove the interface from the instance first so a consistent interface resolution order can be achieved. (Calling gc.collect() is also necessary because we use weakrefs.)

>>> from zope.interface import classImplements
>>> from zope.interface import noLongerProvides
>>> import gc
>>> noLongerProvides(foo, IFoo)
>>> _ = gc.collect()
>>> classImplements(Foo, IFoo)
>>> verify_foo()
True

Testing for attributes

Attributes of the object, be they defined by its class or added by its __init__ method, will be recognized:

>>> @implementer(IFoo)
... class Foo(object):
...     x = 1
...     def __init__(self):
...         self.y = 2

>>> verifyObject(IFoo, Foo())
True

If either attribute is missing, verification will fail by raising an exception.

>>> @implementer(IFoo)
... class Foo(object):
...     x = 1
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The module.IFoo.y attribute was not provided.
>>> @implementer(IFoo)
... class Foo(object):
...     def __init__(self):
...         self.y = 2
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The base.IBase.x attribute was not provided.

If both attributes are missing, an exception is raised reporting both errors.

>>> @implementer(IFoo)
... class Foo(object):
...     pass
>>> verify_foo()
The object <Foo ...> has failed to implement interface ...IFoo:
    The base.IBase.x attribute was not provided
    The module.IFoo.y attribute was not provided

If an attribute is implemented as a property that raises an AttributeError when trying to get its value, the attribute is considered missing:

>>> oname, __name__ = __name__, 'module'
>>> class IFoo(Interface):
...     x = Attribute('The X attribute')
>>> __name__ = oname; del oname
>>> @implementer(IFoo)
... class Foo(object):
...     @property
...     def x(self):
...         raise AttributeError
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The module.IFoo.x attribute was not provided.

Any other exception raised by a property will propagate to the caller of verifyObject:

>>> @implementer(IFoo)
... class Foo(object):
...     @property
...     def x(self):
...         raise Exception
>>> verify_foo()
Traceback (most recent call last):
Exception

Of course, broken properties that are not required by the interface don’t do any harm:

>>> @implementer(IFoo)
... class Foo(object):
...     x = 1
...     @property
...     def y(self):
...         raise Exception
>>> verify_foo()
True

Testing For Methods

Methods are also validated to exist. We’ll start by defining a method that takes one argument. If we don’t provide it, we get an error.

>>> oname, __name__ = __name__, 'module'
>>> class IFoo(Interface):
...    def simple(arg1): "Takes one positional argument"
>>> __name__ = oname; del oname
>>> @implementer(IFoo)
... class Foo(object):
...    pass
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The module.IFoo.simple(arg1) attribute was not provided.

Once they exist, they are checked to be callable, and for compatible signatures.

Not being callable is an error.

>>> Foo.simple = 42
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.simple(arg1) is violated because '42' is not a method.

Taking too few arguments is an error. (Recall that the self argument is implicit.)

>>> Foo.simple = lambda self: "I take no arguments"
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.simple(arg1) is violated because '<lambda>()' doesn't allow enough arguments.

Requiring too many arguments is an error.

>>> Foo.simple = lambda self, a, b: "I require two arguments"
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.simple(arg1) is violated because '<lambda>(a, b)' requires too many arguments.

Variable arguments can be used to implement the required number, as can arguments with defaults.

>>> Foo.simple = lambda self, *args: "Varargs work."
>>> verify_foo()
True
>>> Foo.simple = lambda self, a=1, b=2: "Default args work."
>>> verify_foo()
True

If our interface defines a method that uses variable positional or variable keyword arguments, the implementation must also accept them.

>>> oname, __name__ = __name__, 'module'
>>> class IFoo(Interface):
...    def needs_kwargs(**kwargs): pass
>>> __name__ = oname; del oname
>>> @implementer(IFoo)
... class Foo(object):
...     def needs_kwargs(self, a=1, b=2): pass
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.needs_kwargs(**kwargs) is violated because 'Foo.needs_kwargs(a=1, b=2)' doesn't support keyword arguments.

>>> oname, __name__ = __name__, 'module'
>>> class IFoo(Interface):
...    def needs_varargs(*args): pass
>>> __name__ = oname; del oname
>>> @implementer(IFoo)
... class Foo(object):
...     def needs_varargs(self, **kwargs): pass
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo: The contract of module.IFoo.needs_varargs(*args) is violated because 'Foo.needs_varargs(**kwargs)' doesn't support variable arguments.

Of course, missing attributes are also found and reported, and the source interface of the missing attribute is included. Similarly, when the failing method is from a parent class, that is also reported.

>>> oname, __name__ = __name__, 'base'
>>> class IBase(Interface):
...    def method(arg1): "Takes one positional argument"
>>> __name__ = 'module'
>>> class IFoo(IBase):
...    x = Attribute('The X attribute')
>>> __name__ = oname; del oname
>>> class Base(object):
...    def method(self): "I don't have enough arguments"
>>> @implementer(IFoo)
... class Foo(Base):
...    pass
>>> verify_foo()
The object <Foo...> has failed to implement interface ...IFoo:
    The contract of base.IBase.method(arg1) is violated because 'Base.method()' doesn't allow enough arguments
    The module.IFoo.x attribute was not provided

Verifying Classes

The function verifyClass is used to check that a class implements an interface properly, meaning that its instances properly provide the interface. Many of the same things that verifyObject checks can be checked for classes, but certain conditions, such as the presence of attributes, cannot be verified.

zope.interface.verify.verifyClass(iface, candidate, tentative=False)

Verify that the candidate might correctly provide iface.

>>> from zope.interface.verify import verifyClass
>>> def verify_foo_class():
...    try:
...        return verifyClass(IFoo, Foo)
...    except Invalid as e:
...        print(e)

>>> verify_foo_class()
The object <class 'Foo'> has failed to implement interface ...IFoo: The contract of base.IBase.method(arg1) is violated because 'Base.method(self)' doesn't allow enough arguments.