Merge lp:~leonardr/lazr.restfulclient/server-takes-precedence into lp:lazr.restfulclient

[Leonard Richardson]

Let's say you have a shim object of resource type 'foo'. Because it's a shim, you don't have any real data for it, but you can get some data by accessing one of the many properties of a 'foo'-type object. When you do this, lazr.restful makes a request for the corresponding resource.

But, uh-oh! When lazr.restful makes the request, the representation of this resource says it's not a 'foo' object at all! It's actually a 'bar' object! What to do?

Currently, lazr.restful stubbornly insists that the object is a 'foo' object, and you can only access the features that are common to 'foo' and 'bar'. This branch changes things so that once the representation is received, the resource silently changes into a 'bar' object. You'll only get an error if you tried to access a feature of 'foo' that wasn't in 'bar'.

This is important for my upcoming launchpadlib branch, where 'foo' == 'team' and 'bar' == 'person'.

[Aaron Bentley (abentley)]

I have reservations about letting objects change type, but leonardr has convinced me that this is not a practical problem. The discrepancy would be hard to provoke, because accessing members will cause the object to be loaded.

I would like to see mention in the documentation that WADL doesn't allow inheritance relationships to be explored. Otherwise, this is fine.

review: Approve

=== modified file 'src/lazr/restfulclient/NEWS.txt'
--- src/lazr/restfulclient/NEWS.txt	2010-06-16 16:49:44 +0000
+++ src/lazr/restfulclient/NEWS.txt	2010-06-21 14:30:49 +0000
@@ -2,13 +2,22 @@
 NEWS for lazr.restfulclient
 ===========================
 
+0.9.19 (2010-06-21)
+===================
+
+ - When the representation of a resource, as retrieved from the
+   server, is of a different type than expected, the server value now
+   takes precedence. This means that, in rare situations, a resource
+   may start out presumed to be of one type, and change its
+   capabilities once its representation is fetched from the server.
+
 0.9.18 (2010-06-16)
 ===================
 
- - Made it possible to avoid fetching a representation of every
-   single object looked up from a CollectionWithKeyBasedLookup (by
-   defining .contains_resource_type on the class), potentially
-   improving script performance.
+ - Made it possible to avoid fetching a representation of every single
+   object looked up from a CollectionWithKeyBasedLookup (by defining
+   .collection_of on the class), potentially improving script
+   performance.
 
 0.9.17 (2010-05-10)
 ===================

=== modified file 'src/lazr/restfulclient/docs/toplevel.txt'
--- src/lazr/restfulclient/docs/toplevel.txt	2010-02-11 15:59:16 +0000
+++ src/lazr/restfulclient/docs/toplevel.txt	2010-06-21 14:30:49 +0000
@@ -41,6 +41,86 @@
     >>> print service.recipes[1].dish.name
     Roast chicken
 
+When a collection supports key-based lookups, simply looking up an
+object will not trigger an HTTP request. The HTTP request happens when
+you try to access one of the object's properties.
+
+    >>> import httplib2
+    >>> httplib2.debuglevel = 1
+    >>> debug_service = CookbookWebServiceClient()
+    send: 'GET ...'
+    ...
+    >>> httplib2.debuglevel = 0
+
+    >>> recipe = debug_service.recipes[4]
+
+    >>> sorted(recipe.lp_attributes)
+    ['http_etag', 'id', 'instructions', ...]
+
+    >>> print recipe.instructions
+    send: 'GET /1.0/recipes/4 ...'
+    ...
+    Preheat oven to...
+
+Now, let's imagine that a top-level collection is misconfigured. We
+know that the top-level collection of recipes contains objects whose
+resource type is 'recipe'. But let's tell lazr.restfulclient that that
+collection contains objects of type 'cookbook'.
+
+    >>> from lazr.restfulclient.tests.example import RecipeSet
+    >>> print RecipeSet.collection_of
+    recipe
+    >>> RecipeSet.collection_of = 'cookbook'
+
+Looking up an object will give you something that presents the
+interface of a cookbook.
+
+    >>> not_really_a_cookbook = debug_service.recipes[2]
+    >>> sorted(not_really_a_cookbook.lp_attributes)
+    ['confirmed', 'copyright_date', 'cuisine'...]
+
+But once you try to access one of the object's properties, and the
+HTTP request is made...
+
+    >>> print not_really_a_cookbook.resource_type_link
+    send: 'GET /1.0/recipes/2 ...'
+    ...
+    http://cookbooks.dev/1.0/#recipe
+
+...the server serves a recipe, and so the client-side object takes on
+the properties of a recipe. You can only fool lazr.restfulclient up to
+the point where it has real data to look at.
+
+    >>> sorted(not_really_a_cookbook.lp_attributes)
+    ['http_etag', 'id', 'instructions', ...]
+
+    >>> print not_really_a_cookbook.instructions
+    Draw, singe, stuff, and truss...
+
+This isn't just a defense mechanism: it's a useful feature when a
+top-level collection contains mixed subclasses of some superclass. For
+instance, the launchpadlib library defines the 'people' collection as
+containing 'team' objects, even though it also contains 'person'
+objects, which expose a subset of a team's functionality. All objects
+looked up in that collection start out as team objects, but once an
+object's data is fetched, if it turns out to actually be a person, it
+switches from the "team" interface to the "people" interface.
+
+If you try to access a property based on a resource type the object
+doesn't really implement, you'll get an error.
+
+    >>> not_really_a_cookbook = debug_service.recipes[3]
+    >>> sorted(not_really_a_cookbook.lp_attributes)
+    ['confirmed', 'copyright_date', 'cuisine'...]
+    >>> not_really_a_cookbook.cuisine
+    Traceback (most recent call last):
+    ...
+    AttributeError: 'Entry' object has no attribute 'cuisine'
+
+Cleanup.
+
+    >>> RecipeSet.collection_of = 'recipe'
+
 Versioning
 ==========
 

=== modified file 'src/lazr/restfulclient/resource.py'
--- src/lazr/restfulclient/resource.py	2010-06-16 17:40:18 +0000
+++ src/lazr/restfulclient/resource.py	2010-06-21 14:30:49 +0000
@@ -329,8 +329,19 @@
         if self._wadl_resource.representation is None:
             # Get a representation of the linked resource.
             representation = self._root._browser.get(self._wadl_resource)
+            representation = simplejson.loads(representation)
+            type_link = representation['resource_type_link']
+            if (type_link is not None
+                and type_link != self._wadl_resource.type_url):
+                # In rare cases, the resource type served by the
+                # server conflicts with the type the client thought
+                # this resource had. When this happens, the server
+                # value takes precedence.
+                resource_type = self._root._wadl.get_resource_type(type_link)
+                self._wadl_resource.tag = resource_type.tag
             self.__dict__['_wadl_resource'] = self._wadl_resource.bind(
-                representation, self.JSON_MEDIA_TYPE)
+                representation, self.JSON_MEDIA_TYPE,
+                representation_needs_processing=False)
 
     def __ne__(self, other):
         """Inequality operator."""

=== modified file 'src/lazr/restfulclient/version.txt'
--- src/lazr/restfulclient/version.txt	2010-06-16 16:49:44 +0000
+++ src/lazr/restfulclient/version.txt	2010-06-21 14:30:49 +0000
@@ -1,1 +1,1 @@
-0.9.18
+0.9.19