Merge lp:~leonardr/lazr.restful/multiversion-named-operation into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch shows how to support different named operations in different versions of the web service. I didn't have to change any code because named operations are already looked up based on a combination of (data model object, request). Registering different operations for different request types works automatically.

So this branch just adds some illustrative tests to multiversion.txt.

[Francis J. Lacoste (flacoste)]

On January 7, 2010, Leonard Richardson wrote:
> Leonard Richardson has proposed merging
> lp:~leonardr/lazr.restful/multiversion-named-operation into
> lp:lazr.restful with lp:~leonardr/lazr.restful/multiversion-collection as
> a prerequisite.
>
> Requested reviews:
> LAZR Developers (lazr-developers)
>
>
> This branch shows how to support different named operations in different
> versions of the web service. I didn't have to change any code because
> named operations are already looked up based on a combination of (data
> model object, request). Registering different operations for different
> request types works automatically.
>
> So this branch just adds some illustrative tests to multiversion.txt.
>

Hi Leonard,

I only have one comment on that branch.

  review approve code
  status approved

> === modified file 'src/lazr/restful/docs/multiversion.txt'

> ...
> NotFound: Object: <Contact object...>, name: u'fax'
>
> +We can invoke a named operation. Note that the name of the operation
> +is now 'find' (it was 'findContacts' in 'beta').
> +
> + >>> request_beta = create_web_service_request(
> + ... '/1.0/contacts',
> + ... environ={'QUERY_STRING' : 'ws.op=find&string=Cleo'})
> + >>> operation = request_beta.traverse(None)
> + >>> result = simplejson.loads(operation())
> + >>> [contact['name'] for contact in result['entries']]
> + ['Cleo Python']
> +
> + >>> request_10 = create_web_service_request(
> + ... '/1.0/contacts',
> + ... environ={'QUERY_STRING' : 'ws.op=find&string=111'})
> + >>> operation = request_10.traverse(None)
> + >>> result = simplejson.loads(operation())
> + >>> [contact['fax_number'] for contact in result['entries']]
> + ['111-2121']
> +
> +
> Dev

You might want to show that using the old name would return a 404.

--
Francis J. Lacoste
<email address hidden>

review: Approve (code)

=== modified file 'src/lazr/restful/docs/multiversion.txt'
--- src/lazr/restful/docs/multiversion.txt	2010-01-07 23:42:13 +0000
+++ src/lazr/restful/docs/multiversion.txt	2010-01-07 23:42:14 +0000
@@ -126,9 +126,9 @@
     ...     phone = TextLine(title=u"Phone number", required=True)
     ...     fax = TextLine(title=u"Fax number", required=False)
 
-Here's the interface for the 'set' object that manages the contacts.
+Here's an interface for the 'set' object that manages the
+contacts.
 
-    >>> from zope.interface import implements
     >>> from lazr.restful.interfaces import ITraverseWithGet
     >>> class IContactSet(ITestDataObject, ITraverseWithGet):
     ...     def getAllContacts():
@@ -136,10 +136,14 @@
     ...
     ...     def get(request, name):
     ...         "Retrieve a single contact by name."
+    ...
+    ...     def findContacts(self, string, search_fax):
+    ...         """Find contacts by name, phone number, or fax number."""
 
 Here's a simple implementation of IContact.
 
     >>> from urllib import quote
+    >>> from zope.interface import implements
     >>> from lazr.restful.security import protect_schema
     >>> class Contact:
     ...     implements(IContact)
@@ -176,6 +180,12 @@
     ...     def getAllContacts(self):
     ...         return self.contacts
     ...
+    ...     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 (search_fax and string in contact.fax))]
+    ...
     ...     def __parent__(self, request):
     ...         return getUtility(IServiceRootResource, name=request.version)
     ...
@@ -377,9 +387,13 @@
 Implementing the collection resource
 ====================================
 
-The contact collection itself doesn't change between versions (though
-it could). We'll define it once and register it for every version of
-the web service.
+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.
 
     >>> from lazr.restful import Collection
     >>> from lazr.restful.interfaces import ICollection
@@ -394,19 +408,133 @@
     ...        """Find all the contacts."""
     ...        return self.context.getAllContacts()
 
-Let's make sure ContactCollection implements ICollection.
+Let's make sure it implements ICollection.
 
     >>> from zope.interface.verify import verifyObject
     >>> contact_set = ContactSet()
     >>> verifyObject(ICollection, ContactCollection(contact_set, None))
     True
 
-Once we register ContactCollection as the ICollection implementation,
-we can adapt the ContactSet object to a web service ICollection.
-
+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.
+
+    >>> sm.registerAdapter(
+    ...     ContactCollection, [IContactSet, IWebServiceClientRequest],
+    ...     provided=ICollection)
+
+Make sure the functionality works properly.
+
+    >>> collection = getMultiAdapter(
+    ...     (contact_set, request_beta), ICollection)
+    >>> len(collection.find())
+    2
+
+Implementing the named operations
+---------------------------------
+
+All three versions of the web service publish a named operation for
+searching for contacts, but they publish it in slightly different
+ways. In 'beta' it publishes a named operation called 'findContacts',
+which does a search based on name, phone number, and fax number. In
+'1.0' it publishes the same operation, but the name is
+'find'. In 'dev' the contact set publishes 'find',
+but the functionality is changed to search only the name and phone
+number.
+
+Here's the named operation as implemented in versions 'beta' and '1.0'.
+
+    >>> from lazr.restful import ResourceGETOperation
+    >>> from lazr.restful.fields import CollectionField, Reference
+    >>> from lazr.restful.interfaces import IResourceGETOperation
+    >>> class FindContactsOperationBase(ResourceGETOperation):
+    ...    """An operation that searches for contacts."""
+    ...    implements(IResourceGETOperation)
+    ...
+    ...    params = [ TextLine(__name__='string') ]
+    ...    return_type = CollectionField(value_type=Reference(schema=IContact))
+    ...
+    ...    def call(self, string):
+    ...        try:
+    ...            return self.context.findContacts(string)
+    ...        except ValueError, e:
+    ...            self.request.response.setStatus(400)
+    ...            return str(e)
+
+This operation is registered as the "findContacts" operation in the
+'beta' service, and the 'find' operation in the '1.0' service.
+
+    >>> sm.registerAdapter(
+    ...     FindContactsOperationBase, [IContactSet, IWebServiceRequestBeta],
+    ...     provided=IResourceGETOperation, name="findContacts")
+
+    >>> sm.registerAdapter(
+    ...     FindContactsOperationBase, [IContactSet, IWebServiceRequest10],
+    ...     provided=IResourceGETOperation, name="find")
+
+Here's the slightly different named operation as implemented in
+version 'dev'.
+
+    >>> class FindContactsOperationNoFax(FindContactsOperationBase):
+    ...    """An operation that searches for contacts."""
+    ...
+    ...    def call(self, string):
+    ...        try:
+    ...            return self.context.findContacts(string, False)
+    ...        except ValueError, e:
+    ...            self.request.response.setStatus(400)
+    ...            return str(e)
+
+    >>> sm.registerAdapter(
+    ...     FindContactsOperationNoFax, [IContactSet, IWebServiceRequestDev],
+    ...     provided=IResourceGETOperation, name="find")
+
+The service root resource
+=========================
+
+To make things more interesting we'll define two distinct service
+roots. The 'beta' web service will publish the contact set as
+'contact_list', and subsequent versions will publish it as 'contacts'.
+
+    >>> from lazr.restful.simple import RootResource
+    >>> from zope.traversing.browser.interfaces import IAbsoluteURL
+
+    >>> class BetaServiceRootResource(RootResource):
+    ...     implements(IAbsoluteURL)
+    ...
+    ...     top_level_collections = {
+    ...         'contact_list': (IContact, ContactSet()) }
+
+    >>> class PostBetaServiceRootResource(RootResource):
+    ...     implements(IAbsoluteURL)
+    ...
+    ...     top_level_collections = {
+    ...         'contacts': (IContact, ContactSet()) }
+
+    >>> for version, cls in (('beta', BetaServiceRootResource),
+    ...                      ('1.0', PostBetaServiceRootResource),
+    ...                      ('dev', PostBetaServiceRootResource)):
+    ...     app = cls()
+    ...     sm.registerUtility(app, IServiceRootResource, name=version)
+
+    >>> beta_app = getUtility(IServiceRootResource, 'beta')
+    >>> dev_app = getUtility(IServiceRootResource, 'dev')
+
+    >>> beta_app.top_level_names
+    ['contact_list']
+
+    >>> dev_app.top_level_names
+    ['contacts']
+
+Both classes will use the default lazr.restful code to generate their
+URLs.
+
+    >>> from zope.traversing.browser import absoluteURL
+    >>> from lazr.restful.simple import RootResourceAbsoluteURL
+    >>> for cls in (BetaServiceRootResource, PostBetaServiceRootResource):
+    ...     sm.registerAdapter(
 <<<<<<< TREE
-    >>> for version in ['beta', 'dev', '1.0']:
-    ...     sm.registerAdapter(
     ...         ContactCollection, provided=ICollection, name=version)
 
     >>> dev_collection = getAdapter(contact_set, ICollection, name="dev")
@@ -516,65 +644,6 @@
     http://api.multiversion.dev/dev/
 
 =======
-    >>> for request, ignore in versions:
-    ...     sm.registerAdapter(
-    ...         ContactCollection, [IContactSet, request],
-    ...         provided=ICollection)
-
-    >>> beta_collection = getMultiAdapter(
-    ...     (contact_set, request_beta), ICollection)
-    >>> len(beta_collection.find())
-    2
-
-    >>> dev_collection = getMultiAdapter(
-    ...     (contact_set, request_dev), ICollection)
-    >>> len(dev_collection.find())
-    2
-
-The service root resource
-=========================
-
-To make things more interesting we'll define two distinct service
-roots. The 'beta' web service will publish the contact set as
-'contact_list', and subsequent versions will publish it as 'contacts'.
-
-    >>> from lazr.restful.simple import RootResource
-    >>> from zope.traversing.browser.interfaces import IAbsoluteURL
-
-    >>> class BetaServiceRootResource(RootResource):
-    ...     implements(IAbsoluteURL)
-    ...
-    ...     top_level_collections = {
-    ...         'contact_list': (IContact, ContactSet()) }
-
-    >>> class PostBetaServiceRootResource(RootResource):
-    ...     implements(IAbsoluteURL)
-    ...
-    ...     top_level_collections = {
-    ...         'contacts': (IContact, ContactSet()) }
-
-    >>> for version, cls in (('beta', BetaServiceRootResource),
-    ...                      ('1.0', PostBetaServiceRootResource),
-    ...                      ('dev', PostBetaServiceRootResource)):
-    ...     app = cls()
-    ...     sm.registerUtility(app, IServiceRootResource, name=version)
-
-    >>> beta_app = getUtility(IServiceRootResource, 'beta')
-    >>> dev_app = getUtility(IServiceRootResource, 'dev')
-
-    >>> beta_app.top_level_names
-    ['contact_list']
-
-    >>> dev_app.top_level_names
-    ['contacts']
-
-Both classes will use the default lazr.restful code to generate their
-URLs.
-
-    >>> from zope.traversing.browser import absoluteURL
-    >>> from lazr.restful.simple import RootResourceAbsoluteURL
-    >>> for cls in (BetaServiceRootResource, PostBetaServiceRootResource):
-    ...     sm.registerAdapter(
     ...         RootResourceAbsoluteURL, [cls, IBrowserRequest])
 
     >>> beta_request = create_web_service_request('/beta/')
@@ -671,6 +740,26 @@
     >>> print simplejson.loads(field())
     111-2121
 
+We can invoke a named operation.
+
+    >>> import simplejson
+    >>> request_beta = create_web_service_request(
+    ...     '/beta/contact_list',
+    ...     environ={'QUERY_STRING' : 'ws.op=findContacts&string=Cleo'})
+    >>> operation = request_beta.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['name'] for contact in result['entries']]
+    ['Cleo Python']
+
+    >>> request_beta = create_web_service_request(
+    ...     '/beta/contact_list',
+    ...     environ={'QUERY_STRING' : 'ws.op=findContacts&string=111'})
+
+    >>> operation = request_beta.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['fax'] for contact in result['entries']]
+    ['111-2121']
+
 1.0
 ---
 
@@ -750,6 +839,34 @@
     ...
     NotFound: Object: <Contact object...>, name: u'fax'
 
+We can invoke a named operation. Note that the name of the operation
+is now 'find' (it was 'findContacts' in 'beta').
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=Cleo'})
+    >>> operation = request_10.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['name'] for contact in result['entries']]
+    ['Cleo Python']
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=111'})
+    >>> operation = request_10.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['fax_number'] for contact in result['entries']]
+    ['111-2121']
+
+Attempting to invoke the operation using its 'beta' name won't work.
+
+    >>> request_10 = create_web_service_request(
+    ...     '/1.0/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=findContacts&string=Cleo'})
+    >>> operation = request_10.traverse(None)
+    >>> print operation()
+    No such operation: findContacts
+
 Dev
 ---
 
@@ -822,4 +939,26 @@
     Traceback (most recent call last):
     ...
     NotFound: Object: <Contact object...>, name: u'fax_number'
+
+We can invoke a named operation.
+
+    >>> request_dev = create_web_service_request(
+    ...     '/dev/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=Cleo'})
+    >>> operation = request_dev.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> [contact['name'] for contact in result['entries']]
+    ['Cleo Python']
+
+Note that a search for Cleo's fax number no longer finds anything,
+because the named operation published as 'find' in the 'dev' web
+service doesn't search the fax field.
+
+    >>> request_dev = create_web_service_request(
+    ...     '/dev/contacts',
+    ...     environ={'QUERY_STRING' : 'ws.op=find&string=111'})
+    >>> operation = request_dev.traverse(None)
+    >>> result = simplejson.loads(operation())
+    >>> result['total_size']
+    0
 >>>>>>> MERGE-SOURCE