Skip to content

Commit

Permalink
Merge pull request #174 from zopefoundation/issue171
Browse files Browse the repository at this point in the history 
Make verifyObject/Class collect and raise all errors instead of only the first
  • Loading branch information
@jamadden
jamadden committed Feb 10, 2020
2 parents d6343ee + 3922979 commit 447121d
Show file tree
Hide file tree
Showing 7 changed files with 562 additions and 159 deletions.
15 changes: 10 additions & 5 deletions .travis.yml
View file
Expand Up @@ -82,17 +82,22 @@ before_install:
fi
install:
- pip install -U pip setuptools
- pip install -U coveralls coverage
- pip install -U -e ".[test]"
# virtualenv 20.0 together with terryfy macOS is broken, at least
# with CPython 2.7.17 (https://github.com/pypa/virtualenv/issues/1555):
# it doesn't install or activate the virtualenv correctly and PATH
# isn't setup right. So try to use `python -m` to workaround that.
- python -m pip install -U pip setuptools
- python -m pip install -U coveralls coverage
- python -m pip install -U -e ".[test]"

script:
- which python
- python --version
- coverage run -m unittest discover -s src
- python -m coverage run -m unittest discover -s src
- python setup.py -q bdist_wheel

after_success:
- coveralls
- python -m coveralls
- |
if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
# macpython 3.5 doesn't support recent TLS protocols which causes twine
Expand Down
8 changes: 8 additions & 0 deletions CHANGES.rst
View file
Expand Up @@ -108,6 +108,14 @@
.. caution:: This will break consumers (such as doctests) that
depended on the exact error messages.

- Make ``verifyObject`` and ``verifyClass`` report all errors, if the
candidate object has multiple detectable violations. Previously they
reported only the first error. See `issue
<https://github.com/zopefoundation/zope.interface/issues/171>`_.

Like the above, this will break consumers depending on the exact
output of error messages if more than one error is present.

4.7.1 (2019-11-11)
==================

Expand Down
172 changes: 128 additions & 44 deletions docs/verify.rst
View file
Expand Up @@ -14,6 +14,82 @@ Verifying objects

.. autoexception:: zope.interface.Invalid

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.

.. doctest::

>>> from zope.interface import Interface, Attribute, implementer
>>> from zope.interface import Invalid
>>> from zope.interface.verify import verifyObject
>>> class IBase(Interface):
... x = Attribute("The X attribute")
>>> class IFoo(IBase):
... y = Attribute("The Y attribute")
>>> 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.

.. doctest::

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

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

.. doctest::

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

.. doctest::

>>> verify_foo(tentative=True)
True

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

.. doctest::

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

If all instances will provide the interface, we can
mark the class as implementing it.

.. doctest::

>>> from zope.interface import classImplements
>>> classImplements(Foo, IFoo)
>>> verify_foo()
True


Testing for attributes
----------------------

Expand All @@ -22,46 +98,44 @@ Attributes of the object, be they defined by its class or added by its

.. doctest::

>>> from zope.interface import Interface, Attribute, implementer
>>> from zope.interface.exceptions import BrokenImplementation
>>> class IFoo(Interface):
... x = Attribute("The X attribute")
... y = Attribute("The Y attribute")

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

>>> from zope.interface.verify import verifyObject
>>> verifyObject(IFoo, Foo())
True

If either attribute is missing, verification will fail by raising an
exception. (We'll define a helper to make this easier to show.)
exception.

.. doctest::

>>> def verify_foo():
... foo = Foo()
... try:
... return verifyObject(IFoo, foo)
... except BrokenImplementation as e:
... print(e)

>>> @implementer(IFoo)
... class Foo(object):
... x = 1
>>> verify_foo()
The object <Foo...> has failed to implement interface <InterfaceClass ...IFoo>: The IFoo.y attribute was not provided.
The object <Foo...> has failed to implement interface <...IFoo>: The 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 <InterfaceClass ...IFoo>: The IFoo.x attribute was not provided.
The object <Foo...> has failed to implement interface <...IFoo>: The IBase.x attribute was not provided.

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

.. doctest::

>>> @implementer(IFoo)
... class Foo(object):
... pass
>>> verify_foo()
The object <Foo ...> has failed to implement interface <...IFoo>:
The IBase.x attribute was not provided
The 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:
Expand All @@ -76,7 +150,7 @@ when trying to get its value, the attribute is considered missing:
... def x(self):
... raise AttributeError
>>> verify_foo()
The object <Foo...> has failed to implement interface <InterfaceClass ...IFoo>: The IFoo.x attribute was not provided.
The object <Foo...> has failed to implement interface <...IFoo>: The IFoo.x attribute was not provided.


Any other exception raised by a property will propagate to the caller of
Expand Down Expand Up @@ -122,45 +196,34 @@ that takes one argument. If we don't provide it, we get an error.
... class Foo(object):
... pass
>>> verify_foo()
The object <Foo...> has failed to implement interface <InterfaceClass builtins.IFoo>: The IFoo.simple(arg1) attribute was not provided.

Once they exist, they are checked for compatible signatures. This is a
different type of exception, so we need an updated helper.

.. doctest::
The object <Foo...> has failed to implement interface <...IFoo>: The IFoo.simple(arg1) attribute was not provided.

>>> from zope.interface.exceptions import BrokenMethodImplementation
>>> def verify_foo():
... foo = Foo()
... try:
... return verifyObject(IFoo, foo)
... except BrokenMethodImplementation as e:
... print(e)
Once they exist, they are checked to be callable, and for compatible signatures.

Not being callable is an error.

.. doctest::

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

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

.. doctest::

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

Requiring too many arguments is an error. (Recall that the ``self``
argument is implicit.)
Requiring too many arguments is an error.

.. doctest::

>>> Foo.simple = lambda self, a, b: "I require two arguments"
>>> verify_foo()
The object <Foo...> violates its contract in IFoo.simple(arg1): implementation requires too many arguments.
The object <Foo...> has failed to implement interface <...IFoo>: The contract of 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.
Expand All @@ -185,23 +248,44 @@ variable keyword arguments, the implementation must also accept them.
... class Foo(object):
... def needs_kwargs(self, a=1, b=2): pass
>>> verify_foo()
The object <Foo...> violates its contract in IFoo.needs_kwargs(**kwargs): implementation doesn't support keyword arguments.
The object <Foo...> has failed to implement interface <...IFoo>: The contract of IFoo.needs_kwargs(**kwargs) is violated because 'Foo.needs_kwargs(a=1, b=2)' doesn't support keyword arguments.

>>> class IFoo(Interface):
... def needs_varargs(*args): pass
>>> @implementer(IFoo)
... class Foo(object):
... def needs_varargs(self, **kwargs): pass
>>> verify_foo()
The object <Foo...> violates its contract in IFoo.needs_varargs(*args): implementation doesn't support variable arguments.
The object <Foo...> has failed to implement interface <...IFoo>: The contract of 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.

.. doctest::

>>> class IBase(Interface):
... def method(arg1): "Takes one positional argument"
>>> class IFoo(IBase):
... x = Attribute('The X attribute')
>>> 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 IBase.method(arg1) is violated because 'Base.method()' doesn't allow enough arguments
The 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. Most of the same things that `verifyObject` checks can be
checked for classes.
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.

.. autofunction:: verifyClass

Expand All @@ -211,8 +295,8 @@ checked for classes.
>>> def verify_foo_class():
... try:
... return verifyClass(IFoo, Foo)
... except BrokenMethodImplementation as e:
... except Invalid as e:
... print(e)

>>> verify_foo_class()
The object <class 'Foo'> violates its contract in IFoo.needs_varargs(*args): implementation doesn't support variable arguments.
The object <class 'Foo'> has failed to implement interface <...IFoo>: The contract of IBase.method(arg1) is violated because 'Base.method(self)' doesn't allow enough arguments.

0 comments on commit 447121d

Please sign in to comment.