verify.rst 3.5 KB

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