Merge lp:~leonardr/lazr.restful/test-multiversion-collection into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch changes the multiversion.txt doctest so that there are two different implementations of the 'contact' collection; one used in the 'beta' and '1.0' versions, one used in the 'dev' version. There is no new code; the test merely illustrates something that was already possible.

I also changed the overly long names of the marker interfaces used to designate different versions of the web service. IWebServiceRequestBeta now becomes simply IBetaVersion, and so on.

[Graham Binns (gmb)]

review: Approve (code)

=== modified file 'src/lazr/restful/docs/multiversion.txt'
--- src/lazr/restful/docs/multiversion.txt	2010-01-12 15:06:15 +0000
+++ src/lazr/restful/docs/multiversion.txt	2010-01-26 17:10:25 +0000
@@ -87,7 +87,7 @@
 Every version must have a corresponding subclass of
 IWebServiceClientRequest. Each interface class is registered as a
 named utility implementing IWebServiceVersion. For instance, in the
-example below, the IWebServiceRequest10 class will be registered as
+example below, the I10Version class will be registered as
 the IWebServiceVersion utility with the name "1.0".
 
 When a request comes in, lazr.restful figures out which version the
@@ -99,18 +99,18 @@
 registered automatically.
 
     >>> from lazr.restful.interfaces import IWebServiceClientRequest
-    >>> class IWebServiceRequestBeta(IWebServiceClientRequest):
-    ...     pass
-
-    >>> class IWebServiceRequest10(IWebServiceClientRequest):
-    ...     pass
-
-    >>> class IWebServiceRequestDev(IWebServiceClientRequest):
-    ...     pass
-
-    >>> versions = ((IWebServiceRequestBeta, 'beta'),
-    ...             (IWebServiceRequest10, '1.0'),
-    ...             (IWebServiceRequestDev, 'dev'))
+    >>> class IBetaVersion(IWebServiceClientRequest):
+    ...     pass
+
+    >>> class I10Version(IWebServiceClientRequest):
+    ...     pass
+
+    >>> class IDevVersion(IWebServiceClientRequest):
+    ...     pass
+
+    >>> versions = ((IBetaVersion, 'beta'),
+    ...             (I10Version, '1.0'),
+    ...             (IDevVersion, 'dev'))
 
     >>> from lazr.restful import register_versioned_request_utility
     >>> for cls, version in versions:
@@ -142,6 +142,9 @@
     ...     def getAllContacts():
     ...         "Get all contacts."
     ...
+    ...     def getContactsWithPhone():
+    ...         "Get all contacts that have a phone number."
+    ...
     ...     def findContacts(self, string, search_fax):
     ...         """Find contacts by name, phone number, or fax number."""
 
@@ -168,6 +171,7 @@
 
 Here's a simple ContactSet with a predefined list of contacts.
 
+    >>> from operator import attrgetter
     >>> from zope.publisher.interfaces.browser import IBrowserRequest
     >>> from lazr.restful.interfaces import IServiceRootResource
     >>> from lazr.restful.simple import TraverseWithGet
@@ -188,10 +192,15 @@
     ...     def getAllContacts(self):
     ...         return self.contacts
     ...
+    ...     def getContactsWithPhone(self):
+    ...         return [contact for contact in self.contacts
+    ...                 if contact.phone is not None]
+    ...
     ...     def findContacts(self, string, search_fax=True):
     ...          return [contact for contact in self.contacts
     ...                  if (string in contact.name
-    ...                      or string in contact.phone
+    ...                      or (contact.phone is not None
+    ...                          and string in contact.phone)
     ...                      or (search_fax and string in contact.fax))]
     ...
     ...     @property
@@ -214,7 +223,8 @@
 
     >>> C1 = Contact("Cleo Python", "555-1212", "111-2121")
     >>> C2 = Contact("Oliver Bluth", "10-1000000", "22-2222222")
-    >>> CONTACTS = [C1, C2]
+    >>> C3 = Contact("Fax-your-order Pizza", None, "100-200-300")
+    >>> CONTACTS = [C1, C2, C3]
 
 Defining the web service data model
 ===================================
@@ -289,7 +299,7 @@
     ...         self.context = context
 
     >>> sm.registerAdapter(
-    ...     ContactEntryBeta, [IContact, IWebServiceRequestBeta],
+    ...     ContactEntryBeta, [IContact, IBetaVersion],
     ...     provided=IContactEntry)
 
 By wrapping one of our predefined Contacts in a ContactEntryBeta
@@ -320,7 +330,7 @@
     ...     def fax_number(self):
     ...         return self.context.fax
     >>> sm.registerAdapter(
-    ...     ContactEntry10, [IContact, IWebServiceRequest10],
+    ...     ContactEntry10, [IContact, I10Version],
     ...     provided=IContactEntry)
 
     >>> entry = ContactEntry10(C1, None)
@@ -343,7 +353,7 @@
     ...     def phone_number(self):
     ...         return self.context.phone
     >>> sm.registerAdapter(
-    ...     ContactEntryDev, [IContact, IWebServiceRequestDev],
+    ...     ContactEntryDev, [IContact, IDevVersion],
     ...     provided=IContactEntry)
 
     >>> entry = ContactEntryDev(C1, None)
@@ -378,19 +388,19 @@
 
     >>> from zope.component import getMultiAdapter
     >>> request_beta = create_web_service_request('/beta/')
-    >>> alsoProvides(request_beta, IWebServiceRequestBeta)
+    >>> alsoProvides(request_beta, IBetaVersion)
     >>> beta_entry = getMultiAdapter((C1, request_beta), IEntry)
     >>> print beta_entry.fax
     111-2121
 
     >>> request_10 = create_web_service_request('/1.0/')
-    >>> alsoProvides(request_10, IWebServiceRequest10)
+    >>> alsoProvides(request_10, I10Version)
     >>> one_oh_entry = getMultiAdapter((C1, request_10), IEntry)
     >>> print one_oh_entry.fax_number
     111-2121
 
     >>> request_dev = create_web_service_request('/dev/')
-    >>> alsoProvides(request_dev, IWebServiceRequestDev)
+    >>> alsoProvides(request_dev, IDevVersion)
     >>> dev_entry = getMultiAdapter((C1, request_dev), IEntry)
     >>> print dev_entry.fax
     Traceback (most recent call last):
@@ -402,16 +412,20 @@
 
 The set of contacts publishes a slightly different named operation in
 every version of the web service, so in a little bit we'll be
-implementing three different versions of the same named operation. But
-the contact set itself doesn't change between versions (although it
-could). So it's sufficient to implement one ICollection implementation
-and register it as the implementation for every version of the web
-service.
+implementing three different versions of the same named operation. The
+contact set itself also changes between versions. In the 'beta' and
+'1.0' versions, the contact set serves all contcts. In the 'dev'
+version, the contact set omits contacts that only have a fax
+number. We'll implement this behavior by implementing ICollection
+twice and registering each implementation for the appropriate versions
+of the web service.
 
     >>> from lazr.restful import Collection
     >>> from lazr.restful.interfaces import ICollection
 
-    >>> class ContactCollection(Collection):
+First we'll implement the version used in 'beta' and '1.0'.
+
+    >>> class ContactCollectionBeta(Collection):
     ...     """A collection of contacts, exposed through the web service."""
     ...     adapts(IContactSet)
     ...
@@ -425,24 +439,55 @@
 
     >>> from zope.interface.verify import verifyObject
     >>> contact_set = ContactSet()
-    >>> verifyObject(ICollection, ContactCollection(contact_set, None))
+    >>> verifyObject(ICollection, ContactCollectionBeta(contact_set, None))
     True
 
-Register it as the ICollection adapter for IContactSet. We use a
-generic request interface (IWebServiceClientRequest) rather than a
-specific one like IWebServiceRequestBeta, so that the same
-implementation will be used for every version of the web service.
+Register it as the ICollection adapter for IContactSet in
+IBetaVersion and I10Version.
 
-    >>> sm.registerAdapter(
-    ...     ContactCollection, [IContactSet, IWebServiceClientRequest],
-    ...     provided=ICollection)
+    >>> for version in [IBetaVersion, I10Version]:
+    ...     sm.registerAdapter(
+    ...         ContactCollectionBeta, [IContactSet, version],
+    ...         provided=ICollection)
 
 Make sure the functionality works properly.
 
     >>> collection = getMultiAdapter(
     ...     (contact_set, request_beta), ICollection)
     >>> len(collection.find())
-    2
+    3
+
+    >>> collection = getMultiAdapter(
+    ...     (contact_set, request_10), ICollection)
+    >>> len(collection.find())
+    3
+
+Now let's implement the different version used in 'dev'.
+
+    >>> class ContactCollectionDev(ContactCollectionBeta):
+    ...     def find(self):
+    ...         """Find all the contacts, sorted by name."""
+    ...         return self.context.getContactsWithPhone()
+
+This class also implements ICollection.
+
+    >>> verifyObject(ICollection, ContactCollectionDev(contact_set, None))
+    True
+
+Register it as the ICollection adapter for IContactSet in
+IDevVersion.
+
+    >>> sm.registerAdapter(
+    ...         ContactCollectionDev, [IContactSet, IDevVersion],
+    ...         provided=ICollection)
+
+Make sure the functionality works properly. Note that the contact that
+only has a fax number no longer shows up.
+
+    >>> collection = getMultiAdapter(
+    ...     (contact_set, request_dev), ICollection)
+    >>> [contact.name for contact in collection.find()]
+    ['Cleo Python', 'Oliver Bluth']
 
 Implementing the named operations
 ---------------------------------
@@ -479,11 +524,11 @@
 'beta' service, and the 'find' operation in the '1.0' service.
 
     >>> sm.registerAdapter(
-    ...     FindContactsOperationBase, [IContactSet, IWebServiceRequestBeta],
+    ...     FindContactsOperationBase, [IContactSet, IBetaVersion],
     ...     provided=IResourceGETOperation, name="findContacts")
 
     >>> sm.registerAdapter(
-    ...     FindContactsOperationBase, [IContactSet, IWebServiceRequest10],
+    ...     FindContactsOperationBase, [IContactSet, I10Version],
     ...     provided=IResourceGETOperation, name="find")
 
 Here's the slightly different named operation as implemented in
@@ -500,7 +545,7 @@
     ...            return str(e)
 
     >>> sm.registerAdapter(
-    ...     FindContactsOperationNoFax, [IContactSet, IWebServiceRequestDev],
+    ...     FindContactsOperationNoFax, [IContactSet, IDevVersion],
     ...     provided=IResourceGETOperation, name="find")
 
 The service root resource
@@ -573,14 +618,14 @@
     ...     create_web_service_request)
 
     >>> request_beta = create_web_service_request('/beta/')
-    >>> IWebServiceRequestBeta.providedBy(request_beta)
+    >>> IBetaVersion.providedBy(request_beta)
     False
 
 The traversal process associates the request with a particular version.
 
     >>> request_beta.traverse(None)
     <BetaServiceRootResource object ...>
-    >>> IWebServiceRequestBeta.providedBy(request_beta)
+    >>> IBetaVersion.providedBy(request_beta)
     True
     >>> print request_beta.version
     beta
@@ -620,11 +665,12 @@
 
     >>> body = simplejson.loads(resource())
     >>> body['total_size']
-    2
+    3
     >>> for link in sorted(
     ...     [contact['self_link'] for contact in body['entries']]):
     ...     print link
     http://api.multiversion.dev/beta/contact_list/Cleo%20Python
+    http://api.multiversion.dev/beta/contact_list/Fax-your-order%20Pizza
     http://api.multiversion.dev/beta/contact_list/Oliver%20Bluth
 
 We can traverse through the collection to an entry.
@@ -713,11 +759,12 @@
 
     >>> body = simplejson.loads(resource())
     >>> body['total_size']
-    2
+    3
     >>> for link in sorted(
     ...     [contact['self_link'] for contact in body['entries']]):
     ...     print link
     http://api.multiversion.dev/1.0/contacts/Cleo%20Python
+    http://api.multiversion.dev/1.0/contacts/Fax-your-order%20Pizza
     http://api.multiversion.dev/1.0/contacts/Oliver%20Bluth
 
 We can traverse through the collection to an entry.