[Checkins] SVN: zope.interface/trunk/src/zope/interface/ added tests for verifyObject in its current state

[Thomas Lotze]

Log message for revision 92657:
  added tests for verifyObject in its current state

Changed:
  U   zope.interface/trunk/src/zope/interface/tests/test_verify.py
  A   zope.interface/trunk/src/zope/interface/verify.txt

-=-
Modified: zope.interface/trunk/src/zope/interface/tests/test_verify.py
===================================================================
--- zope.interface/trunk/src/zope/interface/tests/test_verify.py	2008-10-28 16:58:06 UTC (rev 92656)
+++ zope.interface/trunk/src/zope/interface/tests/test_verify.py	2008-10-28 17:04:41 UTC (rev 92657)
@@ -21,6 +21,8 @@
 from zope.interface.exceptions import BrokenMethodImplementation
 
 import unittest
+import zope.testing.doctestunit
+from zope.testing import doctest
 
 class Test(unittest.TestCase):
 
@@ -190,7 +192,12 @@
 
 def test_suite():
     loader=unittest.TestLoader()
-    return loader.loadTestsFromTestCase(Test)
+    return unittest.TestSuite((
+        zope.testing.doctestunit.DocFileSuite(
+            '../verify.txt',
+            optionflags=doctest.NORMALIZE_WHITESPACE),
+        loader.loadTestsFromTestCase(Test),
+        ))
 
 if __name__=='__main__':
     unittest.TextTestRunner().run(test_suite())

Added: zope.interface/trunk/src/zope/interface/verify.txt
===================================================================
--- zope.interface/trunk/src/zope/interface/verify.txt	                        (rev 0)
+++ zope.interface/trunk/src/zope/interface/verify.txt	2008-10-28 17:04:41 UTC (rev 92657)
@@ -0,0 +1,115 @@
+===================================
+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, resp.
+
+
+Verifying classes
+=================
+
+This is covered by unit tests defined in ``zope.interface.tests.test_verify``.
+
+
+Verifying objects
+=================
+
+An object provides an interface iff
+
+- either its class declares that it implements the interfaces, or the object
+  declares that it directly provides the interface
+
+- the object defines all the methods required by the interface
+
+- all the methods have the correct signature
+
+- the object defines all non-method attributes required by the interface
+
+This doctest currently covers only the latter item.
+
+Testing for attributes
+----------------------
+
+Attributes of the object, be they defined by its class or added by its
+``__init__`` method, will be recognized:
+
+>>> from zope.interface import Interface, Attribute, implements
+>>> class IFoo(Interface):
+...     x = Attribute("The X attribute")
+...     y = Attribute("The Y attribute")
+
+>>> class Foo(object):
+...     implements(IFoo)
+...     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:
+
+>>> class Foo(object):
+...     implements(IFoo)
+...     x = 1
+
+>>> verifyObject(IFoo, Foo())
+Traceback (most recent call last):
+BrokenImplementation: An object has failed to implement interface <InterfaceClass __builtin__.IFoo>
+    The y attribute was not provided.
+
+>>> class Foo(object):
+...     implements(IFoo)
+...     def __init__(self):
+...         self.y = 2
+
+>>> verifyObject(IFoo, Foo())
+Traceback (most recent call last):
+BrokenImplementation: An object has failed to implement interface <InterfaceClass __builtin__.IFoo>
+    The x 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:
+
+>>> class IFoo(Interface):
+...     x = Attribute('The X attribute')
+
+>>> class Foo(object):
+...     implements(IFoo)
+...     @property
+...     def x(self):
+...         raise AttributeError
+
+>>> verifyObject(IFoo, Foo())
+Traceback (most recent call last):
+BrokenImplementation: An object has failed to implement interface <InterfaceClass __builtin__.IFoo>
+    The x attribute was not provided.
+
+Any other exception raised by a property should propagate to the caller of
+``verifyObject``, but currently the attribute is just considered missing:
+
+>>> class Foo(object):
+...     implements(IFoo)
+...     @property
+...     def x(self):
+...         raise Exception
+
+>>> verifyObject(IFoo, Foo())
+Traceback (most recent call last):
+BrokenImplementation: An object has failed to implement interface <InterfaceClass __builtin__.IFoo>
+    The x attribute was not provided.
+
+Of course, broken properties that are not required by the interface don't do
+any harm:
+
+>>> class Foo(object):
+...     implements(IFoo)
+...     x = 1
+...     @property
+...     def y(self):
+...         raise Exception
+
+>>> verifyObject(IFoo, Foo())
+True


Property changes on: zope.interface/trunk/src/zope/interface/verify.txt
___________________________________________________________________
Name: svn:keywords
   + Id Rev Date
Name: svn:eol-style
   + native