Merge lp:~leonardr/lazr.restful/web-link into lp:lazr.restful

[Tim Penhey]

Often each entry published by a web service corresponds to an entry on some website. This is the case with the Launchpad web service. It's useful for a web service consumer to know the link to the corresponding object on a website. This branch makes it possible to get the website URL of an object, assuming there's a way to convert a web service request into a website request.

When writing tests I refactored some common code that creates a web service request to an entry resource, so that the test can make assertions about the entry resource.

[lp:~leonardr/lazr.restful/web-link]

139. By Leonard Richardson on 2011-01-20

Added IWebBrowserOriginatingRequest.

140. By Leonard Richardson on 2011-01-21

Added tests.

141. By Leonard Richardson on 2011-01-21

Removed web_link references from web services that don't have a web_link.

142. By Leonard Richardson on 2011-01-21

Merge from trunk, update NEWS.

[Steve Kowalik (stevenk)]

This looks like great work, thanks Leonard.

My only comment is the import on line 68 of the diff, why is that inline?

review: Approve (code*)

[Tim Penhey (thumper)]

review: Approve

[lp:~leonardr/lazr.restful/web-link]

143. By Leonard Richardson on 2011-01-21

Replaced IObject with IReference, allowing us to get rid of obsolete code.

144. By Leonard Richardson on 2011-01-21

Stop coddling people who use IObject, part 2

145. By Leonard Richardson on 2011-01-21

Removed code that was moved into another branch.

146. By Leonard Richardson on 2011-01-21

Merge with parent.

147. By Leonard Richardson on 2011-01-21

Merge with trunk.

148. By Leonard Richardson on 2011-01-24

Fixed imports.

149. By Leonard Richardson on 2011-01-24

Updated NEWS.

=== modified file 'src/lazr/restful/NEWS.txt'
--- src/lazr/restful/NEWS.txt	2011-01-20 20:25:31 +0000
+++ src/lazr/restful/NEWS.txt	2011-01-21 18:26:23 +0000
@@ -2,6 +2,14 @@
 NEWS for lazr.restful
 =====================
 
+0.16.0 (2010-01-21)
+===================
+
+If each entry in the web service corresponds to some object on a
+website, and there's a way of converting a web service request into a
+website request, the web service will now provide website links for
+each entry.
+
 0.15.2 (2010-01-20)
 ===================
 

=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2011-01-19 19:00:10 +0000
+++ src/lazr/restful/_resource.py	2011-01-21 18:26:23 +0000
@@ -47,9 +47,16 @@
 from zope.app.pagetemplate.engine import TrustedAppPT
 from zope import component
 from zope.component import (
-    adapts, getAdapters, getAllUtilitiesRegisteredFor,
-    getGlobalSiteManager, getMultiAdapter, getSiteManager, getUtility,
-    queryMultiAdapter)
+    adapts,
+    getAdapters,
+    getAllUtilitiesRegisteredFor,
+    getGlobalSiteManager,
+    getMultiAdapter,
+    getSiteManager,
+    getUtility,
+    queryAdapter,
+    queryMultiAdapter,
+    )
 from zope.component.interfaces import ComponentLookupError
 from zope.event import notify
 from zope.publisher.http import init_status_codes, status_reasons
@@ -90,6 +97,7 @@
     LAZR_WEBSERVICE_NAME)
 from lazr.restful.utils import (
     extract_write_portion,
+    get_current_browser_request,
     get_current_web_service_request,
     sorted_named_things,
     )
@@ -989,6 +997,12 @@
                 errors.append(modified_read_only_attribute % 'self_link')
             del changeset['self_link']
 
+        if 'web_link' in changeset:
+            if changeset['web_link'] != absoluteURL(
+                self.entry.context, get_current_browser_request()):
+                errors.append(modified_read_only_attribute % 'web_link')
+            del changeset['web_link']
+
         if 'resource_type_link' in changeset:
             if changeset['resource_type_link'] != self.type_url:
                 errors.append(modified_read_only_attribute %
@@ -1400,6 +1414,12 @@
         """
         data = {}
         data['self_link'] = absoluteURL(self.context, self.request)
+        from lazr.restful.interfaces import IWebBrowserOriginatingRequest
+        browser_request = queryAdapter(self.request, IWebBrowserOriginatingRequest)
+        if browser_request is not None:
+            # Objects in the web server correspond to objects on some website.
+            # Provide the link to the correspnding object on the website.
+            data['web_link'] = absoluteURL(self.context, browser_request)
         data['resource_type_link'] = self.type_url
         unmarshalled_field_values = {}
         for name, field in getFieldsInOrder(self.entry.schema):

=== modified file 'src/lazr/restful/example/wsgi/tests/introduction.txt'
--- src/lazr/restful/example/wsgi/tests/introduction.txt	2009-07-07 17:09:31 +0000
+++ src/lazr/restful/example/wsgi/tests/introduction.txt	2011-01-21 18:26:23 +0000
@@ -27,7 +27,8 @@
 
     >>> entry_resource = webservice.get("/pairs/1").jsonBody()
     >>> sorted(entry_resource.keys())
-    [u'http_etag', u'key', u'resource_type_link', u'self_link', u'value']
+    [u'http_etag', u'key', u'resource_type_link', u'self_link',
+     u'value']
 
 You can get a field resource.
 

=== modified file 'src/lazr/restful/interfaces/_rest.py'
--- src/lazr/restful/interfaces/_rest.py	2010-09-06 19:25:17 +0000
+++ src/lazr/restful/interfaces/_rest.py	2011-01-21 18:26:23 +0000
@@ -50,6 +50,7 @@
     'IWebBrowserInitiatedRequest',
     'LAZR_WEBSERVICE_NAME',
     'LAZR_WEBSERVICE_NS',
+    'IWebBrowserOriginatingRequest',
     'IWebServiceClientRequest',
     'IWebServiceLayer',
     'IWebServiceVersion',
@@ -270,6 +271,15 @@
                            "other end of the link.")
 
 
+class IWebBrowserOriginatingRequest(Interface):
+    """A browser request to an object also published on the web service.
+
+    A web framework may define an adapter for this interface, allowing
+    the web service to include, as part of an entry's representation,
+    a link to that same entry as found on the website.
+    """
+
+
 class IWebServiceClientRequest(IBrowserRequest):
     """Interface for requests to the web service."""
     version = Attribute("The version of the web service that the client "

=== modified file 'src/lazr/restful/tests/test_webservice.py'
--- src/lazr/restful/tests/test_webservice.py	2010-10-25 16:31:09 +0000
+++ src/lazr/restful/tests/test_webservice.py	2011-01-21 18:26:23 +0000
@@ -4,6 +4,7 @@
 
 __metaclass__ = type
 
+from contextlib import contextmanager
 from cStringIO import StringIO
 from operator import attrgetter
 from textwrap import dedent
@@ -16,15 +17,26 @@
 from zope.interface.interface import InterfaceClass
 from zope.publisher.browser import TestRequest
 from zope.schema import Choice, Date, Datetime, TextLine
-from zope.security.management import newInteraction, queryInteraction
+from zope.security.management import (
+    endInteraction,
+    newInteraction,
+    queryInteraction,
+    )
 from zope.traversing.browser.interfaces import IAbsoluteURL
 
 from lazr.enum import EnumeratedType, Item
 from lazr.restful import ResourceOperation
 from lazr.restful.fields import Reference
 from lazr.restful.interfaces import (
-    ICollection, IEntry, IResourceGETOperation, IServiceRootResource,
-    IWebServiceConfiguration, IWebServiceClientRequest, IWebServiceVersion)
+    ICollection,
+    IEntry,
+    IResourceGETOperation,
+    IServiceRootResource,
+    IWebBrowserOriginatingRequest,
+    IWebServiceConfiguration,
+    IWebServiceClientRequest,
+    IWebServiceVersion,
+    )
 from lazr.restful import EntryResource, ResourceGETOperation
 from lazr.restful.declarations import (
     exported, export_as_webservice_entry, LAZR_WEBSERVICE_NAME, annotate_exported_methods)
@@ -127,17 +139,19 @@
 
 class DummyAbsoluteURL:
     """Implements IAbsoluteURL for when you don't care what the URL is."""
+    URL = 'http://dummyurl/'
+
     def __init__(self, *args):
         pass
 
     def __str__(self):
-        return 'http://dummyurl/'
+        return self.URL
 
     __call__ = __str__
 
 
 class EntryTestCase(WebServiceTestCase):
-    """A test suite for entries."""
+    """A test suite that defines an entry class."""
 
     testmodule_objects = [HasRestrictedField, IHasRestrictedField]
 
@@ -147,6 +161,81 @@
             DummyAbsoluteURL, [IHasRestrictedField, IWebServiceClientRequest],
             IAbsoluteURL)
 
+    @contextmanager
+    def entry_resource(self):
+        """Create a request to an entry resource, and yield the resource."""
+        entry_class = get_resource_factory(IHasRestrictedField, IEntry)
+        request = getUtility(IWebServiceConfiguration).createRequest(
+            StringIO(""), {})
+        newInteraction(request)
+
+        data_object = HasRestrictedField("")
+        entry = entry_class(data_object, request)
+        resource = EntryResource(data_object, request)
+
+        yield resource
+
+        endInteraction()
+
+
+class TestEntryRead(EntryTestCase):
+
+    def test_entry_includes_web_link_when_available(self):
+        # If a web service request can be adapted to a web*site* request,
+        # the representation of an entry will include a link to the
+        # corresponding entry on the website.
+        #
+        # This is useful when each entry published by the web service
+        # has a human-readable page on some corresponding website. The
+        # web service can publish links to the website for use by Ajax
+        # clients or for other human-interaction purposes.
+
+        # Let's suppose we can use a helper function to convert a web
+        # service request to a website request.
+        class DummyWebsiteRequest:
+            """A request to the website, as opposed to the web service."""
+            implements(IWebBrowserOriginatingRequest)
+
+        def web_service_request_to_website_request(service_request):
+            """Create a corresponding request to the website."""
+            return DummyWebsiteRequest()
+
+        getGlobalSiteManager().registerAdapter(
+            web_service_request_to_website_request,
+            [IWebServiceClientRequest], IWebBrowserOriginatingRequest)
+
+        # Let's also suppose that an IHasRestrictedField has a
+        # different URL on the website than on the web service.
+        class DummyWebsiteURL(DummyAbsoluteURL):
+            """A web-centric implementation of the dummy URL."""
+            URL = 'http://www.website.url/'
+
+        getGlobalSiteManager().registerAdapter(
+            DummyWebsiteURL,
+            [IHasRestrictedField, IWebBrowserOriginatingRequest],
+            IAbsoluteURL)
+
+        # Now a representation of IHasRestrictedField includes a
+        # 'web_link'.
+        with self.entry_resource() as resource:
+            representation = resource.toDataForJSON()
+            self.assertEquals(representation['self_link'], DummyAbsoluteURL.URL)
+            self.assertEquals(representation['web_link'], DummyWebsiteURL.URL)
+
+    def test_entry_omits_web_link_when_not_available(self):
+        # When there is no way of turning a webservice request into a
+        # website request, the 'web_link' attribute is missing from
+        # entry representations.
+
+        with self.entry_resource() as resource:
+            representation = resource.toDataForJSON()
+            self.assertEquals(
+                representation['self_link'], DummyAbsoluteURL.URL)
+            self.assertFalse('web_link' in representation)
+
+
+class TestEntryWrite(EntryTestCase):
+
     def test_applyChanges_binds_to_resource_context(self):
         """Make sure applyChanges binds fields to the resource context.
 
@@ -155,26 +244,21 @@
         InterfaceRestrictedField is bound to an object that doesn't
         expose the right interface, it will raise an exception.
         """
-        entry_class = get_resource_factory(IHasRestrictedField, IEntry)
-        request = getUtility(IWebServiceConfiguration).createRequest(
-            StringIO(""), {})
-
-        data_object = HasRestrictedField("")
-        entry = entry_class(data_object, request)
-        resource = EntryResource(data_object, request)
-        entry.schema['a_field'].restrict_to_interface = IHasRestrictedField
-        self.assertEquals(resource.entry.a_field, '')
-        resource.applyChanges({'a_field': u'a_value'})
-        self.assertEquals(resource.entry.a_field, 'a_value')
-
-        # Make sure that IHasRestrictedField itself works correctly.
-        class IOtherInterface(Interface):
-            """An interface not provided by IHasRestrictedField."""
-            pass
-        entry.schema['a_field'].restrict_to_interface = IOtherInterface
-        self.assertRaises(AssertionError, resource.applyChanges,
-                          {'a_field': u'a_new_value'})
-        self.assertEquals(resource.entry.a_field, 'a_value')
+        with self.entry_resource() as resource:
+            entry = resource.entry
+            entry.schema['a_field'].restrict_to_interface = IHasRestrictedField
+            self.assertEquals(entry.a_field, '')
+            resource.applyChanges({'a_field': u'a_value'})
+            self.assertEquals(entry.a_field, 'a_value')
+
+            # Make sure that IHasRestrictedField itself works correctly.
+            class IOtherInterface(Interface):
+                """An interface not provided by IHasRestrictedField."""
+                pass
+            entry.schema['a_field'].restrict_to_interface = IOtherInterface
+            self.assertRaises(AssertionError, resource.applyChanges,
+                              {'a_field': u'a_new_value'})
+            self.assertEquals(resource.entry.a_field, 'a_value')
 
 
 class UnicodeChoice(EnumeratedType):
@@ -459,6 +543,8 @@
         self.assertEquals("2.0", webservice_request.version)
         self.assertTrue(marker_20.providedBy(webservice_request))
 
+        endInteraction()
+
 
 def additional_tests():
     return unittest.TestLoader().loadTestsFromName(__name__)

=== modified file 'src/lazr/restful/version.txt'
--- src/lazr/restful/version.txt	2011-01-20 20:25:31 +0000
+++ src/lazr/restful/version.txt	2011-01-21 18:26:23 +0000
@@ -1,1 +1,1 @@
-0.15.2
+0.16.0