← Back to branch summary

~crunch.io/ubuntu/precise/zope.interface/unstable

« back to all changes in this revision

Viewing changes to docs/verify.rst

  • Committer: Joseph Tate
  • Date: 2013-02-04 19:16:30 UTC
  • mfrom: (1.1.4)
  • Revision ID: jtate@dragonstrider.com-20130204191630-ye0hqihd37tdk47r
Update package version

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/verify.rst
 
1
===================================
 
2
Verifying interface implementations
 
3
===================================
 
4
 
 
5
The ``zope.interface.verify`` module provides functions that test whether a
 
6
given interface is implemented by a class or provided by an object, resp.
 
7
 
 
8
 
 
9
Verifying classes
 
10
=================
 
11
 
 
12
This is covered by unit tests defined in ``zope.interface.tests.test_verify``.
 
13
 
 
14
 
 
15
Verifying objects
 
16
=================
 
17
 
 
18
An object provides an interface if
 
19
 
 
20
- either its class declares that it implements the interfaces, or the object
 
21
  declares that it directly provides the interface
 
22
 
 
23
- the object defines all the methods required by the interface
 
24
 
 
25
- all the methods have the correct signature
 
26
 
 
27
- the object defines all non-method attributes required by the interface
 
28
 
 
29
This doctest currently covers only the latter item.
 
30
 
 
31
Testing for attributes
 
32
----------------------
 
33
 
 
34
Attributes of the object, be they defined by its class or added by its
 
35
``__init__`` method, will be recognized:
 
36
 
 
37
.. doctest::
 
38
 
 
39
   >>> from zope.interface import Interface, Attribute, implements
 
40
   >>> from zope.interface.exceptions import BrokenImplementation
 
41
   >>> class IFoo(Interface):
 
42
   ...     x = Attribute("The X attribute")
 
43
   ...     y = Attribute("The Y attribute")
 
44
 
 
45
   >>> class Foo(object):
 
46
   ...     implements(IFoo)
 
47
   ...     x = 1
 
48
   ...     def __init__(self):
 
49
   ...         self.y = 2
 
50
 
 
51
   >>> from zope.interface.verify import verifyObject
 
52
   >>> verifyObject(IFoo, Foo())
 
53
   True
 
54
 
 
55
If either attribute is missing, verification will fail:
 
56
 
 
57
.. doctest::
 
58
 
 
59
   >>> class Foo(object):
 
60
   ...     implements(IFoo)
 
61
   ...     x = 1
 
62
   >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
 
63
   ...     verifyObject(IFoo, Foo())
 
64
   ... except BrokenImplementation, e:
 
65
   ...     print str(e)
 
66
   An object has failed to implement interface <InterfaceClass ...IFoo>
 
67
   <BLANKLINE>
 
68
           The y attribute was not provided.
 
69
   <BLANKLINE>
 
70
   >>> class Foo(object):
 
71
   ...     implements(IFoo)
 
72
   ...     def __init__(self):
 
73
   ...         self.y = 2
 
74
   >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
 
75
   ...     verifyObject(IFoo, Foo())
 
76
   ... except BrokenImplementation, e:
 
77
   ...     print str(e)
 
78
   An object has failed to implement interface <InterfaceClass ...IFoo>
 
79
   <BLANKLINE>
 
80
           The x attribute was not provided.
 
81
   <BLANKLINE>
 
82
 
 
83
If an attribute is implemented as a property that raises an AttributeError
 
84
when trying to get its value, the attribute is considered missing:
 
85
 
 
86
.. doctest::
 
87
 
 
88
   >>> class IFoo(Interface):
 
89
   ...     x = Attribute('The X attribute')
 
90
   >>> class Foo(object):
 
91
   ...     implements(IFoo)
 
92
   ...     @property
 
93
   ...     def x(self):
 
94
   ...         raise AttributeError
 
95
   >>> try: #doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
 
96
   ...     verifyObject(IFoo, Foo())
 
97
   ... except BrokenImplementation, e:
 
98
   ...     print str(e)
 
99
   An object has failed to implement interface <InterfaceClass ...IFoo>
 
100
   <BLANKLINE>
 
101
           The x attribute was not provided.
 
102
   <BLANKLINE>
 
103
 
 
104
Any other exception raised by a property will propagate to the caller of
 
105
``verifyObject``:
 
106
 
 
107
.. doctest::
 
108
 
 
109
   >>> class Foo(object):
 
110
   ...     implements(IFoo)
 
111
   ...     @property
 
112
   ...     def x(self):
 
113
   ...         raise Exception
 
114
   >>> verifyObject(IFoo, Foo())
 
115
   Traceback (most recent call last):
 
116
   Exception
 
117
 
 
118
Of course, broken properties that are not required by the interface don't do
 
119
any harm:
 
120
 
 
121
.. doctest::
 
122
 
 
123
   >>> class Foo(object):
 
124
   ...     implements(IFoo)
 
125
   ...     x = 1
 
126
   ...     @property
 
127
   ...     def y(self):
 
128
   ...         raise Exception
 
129
   >>> verifyObject(IFoo, Foo())
 
130
   True