Merge lp:~leonardr/lazr.restful/launchpad-field-put into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This is a backport of lp:~leonardr/lazr.restful/380959-field-patch to the lazr.restful branch used by Launchpad.

I had a lot of trouble running the tests due to dependency problems, but once I ran it there was only one real problem. The call to field.bind() in applyChanges() passed in self.entry, when it should have passed in self.entry.context. This didn't break the lazr.restful tests, because changes to a generated entry's fields are automatically passed on to the entry's context. But it did break some launchpad tests, because the ValidPersonOrTeam vocabulary field explicitly checks the type of the thing it's bound to.

I'll forward-port the fix, but is it worth trying to also recreate the ValidPersonOrTeam test case within lazr.restful?

[Francis J. Lacoste (flacoste)]

I think it's worth adding a test. I don't think re-implementing ValidPersonOrTeam is the right way to do, but there should be a test that asserts that the correct object is passed in by the API.

review: Approve

=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2009-04-06 16:57:08 +0000
+++ src/lazr/restful/_resource.py	2009-06-02 16:04:54 +0000
@@ -48,16 +48,19 @@
 from zope.interface import (
     implementer, implements, implementedBy, providedBy, Interface)
 from zope.interface.interfaces import IInterface
+from zope.location.interfaces import ILocation
 from zope.pagetemplate.pagetemplatefile import PageTemplateFile
 from zope.proxy import isProxy
 from zope.publisher.interfaces import NotFound
+from zope.publisher.interfaces.http import IHTTPRequest
 from zope.schema import ValidationError, getFieldsInOrder
 from zope.schema.interfaces import (
     ConstraintNotSatisfied, IBytes, IField, IObject)
 from zope.security.interfaces import Unauthorized
 from zope.security.proxy import removeSecurityProxy
 from zope.security.management import checkPermission
-from zope.traversing.browser import absoluteURL
+from zope.traversing.browser import absoluteURL, AbsoluteURL
+from zope.traversing.browser.interfaces import IAbsoluteURL
 
 from lazr.batchnavigator import BatchNavigator
 from lazr.enum import BaseItem
@@ -838,6 +841,18 @@
             self.request.response.setHeader("Allow", allow_string)
         return self.applyTransferEncoding(result)
 
+    def processAsJSONDocument(self, media_type, representation):
+        """Process an incoming representation as a JSON document."""
+        if not media_type.startswith(self.JSON_TYPE):
+            self.request.response.setStatus(415)
+            return None, 'Expected a media type of %s.' % self.JSON_TYPE
+        try:
+            h = simplejson.loads(unicode(representation))
+        except ValueError:
+            self.request.response.setStatus(400)
+            return None, "Entity-body was not a well-formed JSON document."
+        return h, None
+
 
 class EntryHTMLView:
     """An HTML view of an entry."""
@@ -862,274 +877,29 @@
         return self.HTML_TEMPLATE.pt_render(namespace)
 
 
-class EntryFieldResource(ReadOnlyResource, FieldUnmarshallerMixin):
-    """An individual field of an entry."""
-    implements(IEntryFieldResource, IJSONPublishable)
-
-    SUPPORTED_CONTENT_TYPES = [HTTPResource.JSON_TYPE,
-                               HTTPResource.XHTML_TYPE]
-
-    def __init__(self, context, request):
-        """Initialize with respect to a context and request."""
-        super(EntryFieldResource, self).__init__(context, request)
-        self.entry = self.context.entry
-
-    def do_GET(self):
-        """Create a representation of a single field."""
-        media_type = self.handleConditionalGET()
-        if media_type is None:
-            # The conditional GET succeeded. Serve nothing.
-            return ""
-        else:
-            self.request.response.setHeader('Content-Type', media_type)
-            return self._representation(media_type)
-
-    def _getETagCore(self, unmarshalled_field_values=None):
-        """Calculate the ETag for an entry field.
-
-        The core of the ETag is the field value itself.
-        """
-        name, value = self._unmarshallField(
-            self.context.name, self.context.field)
-        return str(value)
-
-    def _representation(self, media_type):
-        """Create a representation of the field value."""
-        if media_type == self.JSON_TYPE:
-            name, value = self._unmarshallField(
-                self.context.name, self.context.field, CLOSEUP_DETAIL)
-            return simplejson.dumps(value)
-        elif media_type == self.XHTML_TYPE:
-            name, value = self.unmarshallFieldToHTML(
-                self.context.name, self.context.field)
-            return value
-        else:
-            raise AssertionError(
-                    "No representation implementation for media type %s"
-                    % media_type)
-
-
-class EntryField:
-    implements(IEntryField)
-
-    def __init__(self, entry, field, name):
-        """Initialize with respect to a named field of an entry."""
-        self.entry = entry
-        self.field = field.bind(entry)
-        self.name = name
-
-
-class EntryResource(ReadWriteResource, CustomOperationResourceMixin,
-                    FieldUnmarshallerMixin):
-    """An individual object, published to the web."""
-    implements(IEntryResource, IJSONPublishable)
-
-    SUPPORTED_CONTENT_TYPES = [HTTPResource.WADL_TYPE,
-                               HTTPResource.XHTML_TYPE,
-                               HTTPResource.JSON_TYPE]
-
-    def __init__(self, context, request):
-        """Associate this resource with a specific object and request."""
-        super(EntryResource, self).__init__(context, request)
-        self.entry = IEntry(context)
-
-    def _getETagCore(self, unmarshalled_field_values=None):
-        """Calculate the ETag for an entry.
-
-        :arg unmarshalled_field_values: A dict mapping field names to
-        unmarshalled values, obtained during some other operation such
-        as the construction of a representation.
-        """
-        values = []
-        for name, field in getFieldsInOrder(self.entry.schema):
-            if self.isModifiableField(field, False):
-                if (unmarshalled_field_values is not None
-                    and unmarshalled_field_values.get(name)):
-                    value = unmarshalled_field_values[name]
-                else:
-                    ignored, value = self._unmarshallField(name, field)
-                values.append(unicode(value))
-        return "\0".join(values).encode("utf-8")
-
-    def toDataForJSON(self):
-        """Turn the object into a simple data structure."""
-        return self.toDataStructure(self.JSON_TYPE)
-
-    def toDataStructure(self, media_type):
-        """Turn the object into a simple data structure.
-
-        In this case, a dictionary containing all fields defined by
-        the resource interface.
-
-        The values in the dictionary may differ depending on the value
-        of media_type.
-        """
-        data = {}
-        data['self_link'] = absoluteURL(self.context, self.request)
-        data['resource_type_link'] = self.type_url
-        unmarshalled_field_values = {}
-        for name, field in getFieldsInOrder(self.entry.schema):
-            if media_type == self.JSON_TYPE:
-                repr_name, repr_value = self._unmarshallField(name, field)
-            elif media_type == self.XHTML_TYPE:
-                repr_name, repr_value = self.unmarshallFieldToHTML(
-                    name, field)
-            else:
-                raise AssertionError(
-                        "Cannot create data structure for media type %s"
-                        % media_type)
-            data[repr_name] = repr_value
-            unmarshalled_field_values[name] =  repr_value
-
-        etag = self.getETag(media_type, unmarshalled_field_values)
-        data['http_etag'] = etag
-        return data
-
-    def toXHTML(self):
-        """Represent this resource as an XHTML document."""
-        view = getMultiAdapter(
-            (self.context, self.request),
-            name="lazr.restful.EntryResource")
-        return view()
-
-    def processAsJSONHash(self, media_type, representation):
-        """Process an incoming representation as a JSON hash.
-
-        :param media_type: The specified media type of the incoming
-        representation.
-
-        :representation: The incoming representation:
-
-        :return: A tuple (dictionary, error). 'dictionary' is a Python
-        dictionary corresponding to the incoming JSON hash. 'error' is
-        an error message if the incoming representation could not be
-        processed. If there is an error, this method will set an
-        appropriate HTTP response code.
-        """
-
-        if not media_type.startswith(self.JSON_TYPE):
-            self.request.response.setStatus(415)
-            return None, 'Expected a media type of %s.' % self.JSON_TYPE
-        try:
-            h = simplejson.loads(unicode(representation))
-        except ValueError:
-            self.request.response.setStatus(400)
-            return None, "Entity-body was not a well-formed JSON document."
-        if not isinstance(h, dict):
-            self.request.response.setStatus(400)
-            return None, 'Expected a JSON hash.'
-        return h, None
-
-    def do_GET(self):
-        """Render an appropriate representation of the entry."""
-        # Handle a custom operation, probably a search.
-        operation_name = self.request.form.pop('ws.op', None)
-        if operation_name is not None:
-            result = self.handleCustomGET(operation_name)
-            if isinstance(result, basestring):
-                # The custom operation took care of everything and
-                # just needs this string served to the client.
-                return result
-        else:
-            # No custom operation was specified. Implement a standard
-            # GET, which serves a JSON or WADL representation of the
-            # entry.
-            media_type = self.handleConditionalGET()
-            if media_type is None:
-                # The conditional GET succeeded. Serve nothing.
-                return ""
-            else:
-                self.request.response.setHeader('Content-Type', media_type)
-                return self._representation(media_type)
-
-    def do_PUT(self, media_type, representation):
-        """Modify the entry's state to match the given representation.
-
-        A PUT is just like a PATCH, except the given representation
-        must be a complete representation of the entry.
-        """
-        changeset, error = self.processAsJSONHash(media_type, representation)
-        if error is not None:
-            return error
-
-        # Make sure the representation includes values for all
-        # writable attributes.
-        # Get the fields ordered by name so that we always evaluate them in
-        # the same order. This is needed to predict errors when testing.
-        for name, field in getFieldsInOrder(self.entry.schema):
-            if not self.isModifiableField(field, True):
-                continue
-            field = field.bind(self.context)
-            marshaller = getMultiAdapter((field, self.request),
-                                         IFieldMarshaller)
-            repr_name = marshaller.representation_name
-            if (changeset.get(repr_name) is None
-                and getattr(self.entry, name) is not None):
-                # This entry has a value for the attribute, but the
-                # entity-body of the PUT request didn't make any assertion
-                # about the attribute. The resource's behavior under HTTP
-                # is undefined; we choose to send an error.
-                self.request.response.setStatus(400)
-                return ("You didn't specify a value for the attribute '%s'."
-                        % repr_name)
-        return self._applyChanges(changeset)
-
-    def do_PATCH(self, media_type, representation):
-        """Apply a JSON patch to the entry."""
-        changeset, error = self.processAsJSONHash(media_type, representation)
-        if error is not None:
-            return error
-        return self._applyChanges(changeset)
-
-    @property
-    def type_url(self):
-        "The URL to the resource type for this resource."
-        adapter = EntryAdapterUtility(self.entry.__class__)
-
-        return "%s#%s" % (
-            absoluteURL(self.request.publication.getApplication(
-                    self.request), self.request),
-            adapter.singular_type)
-
-    def isModifiableField(self, field, is_external_client):
-        """Returns true if this field's value can be changed.
-
-        Collection fields, and fields that are not part of the web
-        service interface, are never modifiable. Read-only fields are
-        not modifiable by external clients.
-
-        :param is_external_client: Whether the code trying to modify
-        the field is an external client. Read-only fields cannot be
-        directly modified from external clients, but they might change
-        as side effects of other changes.
-        """
-        if (ICollectionField.providedBy(field)
-            or field.__name__.startswith('_')):
-            return False
-        if field.readonly:
-            return not is_external_client
-        return True
-
-    def _representation(self, media_type):
-        """Return a representation of this entry, of the given media type."""
-        if media_type == self.WADL_TYPE:
-            return self.toWADL().encode("utf-8")
-        elif media_type == self.JSON_TYPE:
-            return simplejson.dumps(self, cls=ResourceJSONEncoder)
-        elif media_type == self.XHTML_TYPE:
-            return self.toXHTML().encode("utf-8")
-        else:
-            raise AssertionError(
-                    "No representation implementation for media type %s"
-                    % media_type)
-
-    def _applyChanges(self, changeset):
+class UpdatesEntryMixin:
+    """A resource that updates some aspect of an IEntry.
+
+    A class that inherits from this mixin is expected to define an
+    attribute 'entry' containing the IEntry to be updated.
+    """
+
+    def __init__(self, context, request):
+        """A basic constructor."""
+        # Like all mixin classes, this class is designed to be used
+        # with multiple inheritance. That requires defining __init__
+        # to call the next constructor in the chain, which means using
+        # super() even though this class itself has no superclass.
+        super(UpdatesEntryMixin, self).__init__(context, request)
+
+    def applyChanges(self, changeset):
         """Apply a dictionary of key-value pairs as changes to an entry.
 
         :param changeset: A dictionary. Should come from an incoming
         representation.
 
-        :return: An error message to be propagated to the client.
+        :return: If there was an error, a string error message to be
+        propagated to the client.
         """
         changeset = copy.copy(changeset)
         validated_changeset = {}
@@ -1140,7 +910,7 @@
         modified_read_only_attribute = ("%s: You tried to modify a "
                                         "read-only attribute.")
         if 'self_link' in changeset:
-            if changeset['self_link'] != absoluteURL(self.context,
+            if changeset['self_link'] != absoluteURL(self.entry.context,
                                                      self.request):
                 errors.append(modified_read_only_attribute % 'self_link')
             del changeset['self_link']
@@ -1165,7 +935,7 @@
             if name.startswith('_'):
                 # This field is not part of the web service interface.
                 continue
-            field = field.bind(self.context)
+            field = field.bind(self.entry.context)
             marshaller = getMultiAdapter((field, self.request),
                                          IFieldMarshaller)
             repr_name = marshaller.representation_name
@@ -1306,7 +1076,7 @@
             self.entry.context, providing=providedBy(self.entry.context))
 
         # Store the entry's current URL so we can see if it changes.
-        original_url = absoluteURL(self.context, self.request)
+        original_url = absoluteURL(self.entry.context, self.request)
         # Make the changes.
         for field, (name, value) in validated_changeset.items():
             field.set(self.entry, value)
@@ -1326,22 +1096,300 @@
             edited_fields=validated_changeset.keys())
         notify(event)
 
-        # If the modification caused the entry's URL to change, tell
-        # the client about the new URL.
-        new_url = absoluteURL(self.context, self.request)
-        if new_url != original_url:
+        new_url = absoluteURL(self.entry.context, self.request)
+        if new_url == original_url:
+            # The resource did not move. Serve a new representation of
+            # it. This might not necessarily be a representation of
+            # the whole entry!
+            self.request.response.setStatus(209)
+            media_type = self.getPreferredSupportedContentType()
+            self.request.response.setHeader('Content-type', media_type)
+            return self._representation(media_type)
+        else:
+            # The object moved. Serve a redirect to its new location.
+            # This might not necessarily be the location of the entry!
             self.request.response.setStatus(301)
-            self.request.response.setHeader('Location', new_url)
+            self.request.response.setHeader(
+                'Location', absoluteURL(self.context, self.request))
             # RFC 2616 says the body of a 301 response, if present,
             # SHOULD be a note linking to the new object.
             return ''
 
-        # If the object didn't move, serve up its representation.
-        self.request.response.setStatus(209)
-
-        media_type = self.getPreferredSupportedContentType()
-        self.request.response.setHeader('Content-type', media_type)
-        return self._representation(media_type)
+
+class EntryFieldResource(FieldUnmarshallerMixin, UpdatesEntryMixin,
+                         ReadWriteResource):
+    """An individual field of an entry."""
+    implements(IEntryFieldResource, IJSONPublishable)
+
+    SUPPORTED_CONTENT_TYPES = [HTTPResource.JSON_TYPE,
+                               HTTPResource.XHTML_TYPE]
+
+    def __init__(self, context, request):
+        """Initialize with respect to a context and request."""
+        super(EntryFieldResource, self).__init__(context, request)
+        self.entry = self.context.entry
+
+    def do_GET(self):
+        """Create a representation of a single field."""
+        media_type = self.handleConditionalGET()
+        if media_type is None:
+            # The conditional GET succeeded. Serve nothing.
+            return ""
+        else:
+            self.request.response.setHeader('Content-Type', media_type)
+            return self._representation(media_type)
+
+    def do_PUT(self, media_type, representation):
+        """Overwrite the field's existing value with a new value."""
+        value, error = self.processAsJSONDocument(media_type, representation)
+        if value is None:
+            return value, error
+        changeset = {self.context.field.__name__ : value}
+        return self.applyChanges(changeset)
+
+    do_PATCH = do_PUT
+
+    def _getETagCore(self, unmarshalled_field_values=None):
+        """Calculate the ETag for an entry field.
+
+        The core of the ETag is the field value itself.
+        """
+        name, value = self._unmarshallField(
+            self.context.name, self.context.field)
+        return str(value)
+
+    def _representation(self, media_type):
+        """Create a representation of the field value."""
+        if media_type == self.JSON_TYPE:
+            name, value = self._unmarshallField(
+                self.context.name, self.context.field, CLOSEUP_DETAIL)
+            return simplejson.dumps(value)
+        elif media_type == self.XHTML_TYPE:
+            name, value = self.unmarshallFieldToHTML(
+                self.context.name, self.context.field)
+            return value
+        else:
+            raise AssertionError(
+                    "No representation implementation for media type %s"
+                    % media_type)
+
+
+class EntryField:
+    """A schema field bound by name to a particular entry."""
+    implements(IEntryField, ILocation)
+
+    def __init__(self, entry, field, name):
+        """Initialize with respect to a named field of an entry."""
+        self.entry = entry
+        self.field = field.bind(entry)
+        self.name = name
+
+        # ILocation implementation
+        self.__parent__ = self.entry.context
+        self.__name__ = self.name
+
+
+class EntryResource(CustomOperationResourceMixin,
+                    FieldUnmarshallerMixin, UpdatesEntryMixin,
+                    ReadWriteResource):
+    """An individual object, published to the web."""
+    implements(IEntryResource, IJSONPublishable)
+
+    SUPPORTED_CONTENT_TYPES = [HTTPResource.WADL_TYPE,
+                               HTTPResource.XHTML_TYPE,
+                               HTTPResource.JSON_TYPE]
+
+    def __init__(self, context, request):
+        """Associate this resource with a specific object and request."""
+        super(EntryResource, self).__init__(context, request)
+        self.entry = IEntry(context)
+
+    def _getETagCore(self, unmarshalled_field_values=None):
+        """Calculate the ETag for an entry.
+
+        :arg unmarshalled_field_values: A dict mapping field names to
+        unmarshalled values, obtained during some other operation such
+        as the construction of a representation.
+        """
+        values = []
+        for name, field in getFieldsInOrder(self.entry.schema):
+            if self.isModifiableField(field, False):
+                if (unmarshalled_field_values is not None
+                    and unmarshalled_field_values.get(name)):
+                    value = unmarshalled_field_values[name]
+                else:
+                    ignored, value = self._unmarshallField(name, field)
+                values.append(unicode(value))
+        return "\0".join(values).encode("utf-8")
+
+    def toDataForJSON(self):
+        """Turn the object into a simple data structure."""
+        return self.toDataStructure(self.JSON_TYPE)
+
+    def toDataStructure(self, media_type):
+        """Turn the object into a simple data structure.
+
+        In this case, a dictionary containing all fields defined by
+        the resource interface.
+
+        The values in the dictionary may differ depending on the value
+        of media_type.
+        """
+        data = {}
+        data['self_link'] = absoluteURL(self.context, self.request)
+        data['resource_type_link'] = self.type_url
+        unmarshalled_field_values = {}
+        for name, field in getFieldsInOrder(self.entry.schema):
+            if media_type == self.JSON_TYPE:
+                repr_name, repr_value = self._unmarshallField(name, field)
+            elif media_type == self.XHTML_TYPE:
+                repr_name, repr_value = self.unmarshallFieldToHTML(
+                    name, field)
+            else:
+                raise AssertionError(
+                        "Cannot create data structure for media type %s"
+                        % media_type)
+            data[repr_name] = repr_value
+            unmarshalled_field_values[name] =  repr_value
+
+        etag = self.getETag(media_type, unmarshalled_field_values)
+        data['http_etag'] = etag
+        return data
+
+    def toXHTML(self):
+        """Represent this resource as an XHTML document."""
+        view = getMultiAdapter(
+            (self.context, self.request),
+            name="lazr.restful.EntryResource")
+        return view()
+
+    def processAsJSONHash(self, media_type, representation):
+        """Process an incoming representation as a JSON hash.
+
+        :param media_type: The specified media type of the incoming
+        representation.
+
+        :representation: The incoming representation:
+
+        :return: A tuple (dictionary, error). 'dictionary' is a Python
+        dictionary corresponding to the incoming JSON hash. 'error' is
+        an error message if the incoming representation could not be
+        processed. If there is an error, this method will set an
+        appropriate HTTP response code.
+        """
+
+        value, error = self.processAsJSONDocument(media_type, representation)
+        if value is None:
+            return value, error
+        if not isinstance(value, dict):
+            self.request.response.setStatus(400)
+            return None, 'Expected a JSON hash.'
+        return value, None
+
+    def do_GET(self):
+        """Render an appropriate representation of the entry."""
+        # Handle a custom operation, probably a search.
+        operation_name = self.request.form.pop('ws.op', None)
+        if operation_name is not None:
+            result = self.handleCustomGET(operation_name)
+            if isinstance(result, basestring):
+                # The custom operation took care of everything and
+                # just needs this string served to the client.
+                return result
+        else:
+            # No custom operation was specified. Implement a standard
+            # GET, which serves a JSON or WADL representation of the
+            # entry.
+            media_type = self.handleConditionalGET()
+            if media_type is None:
+                # The conditional GET succeeded. Serve nothing.
+                return ""
+            else:
+                self.request.response.setHeader('Content-Type', media_type)
+                return self._representation(media_type)
+
+    def do_PUT(self, media_type, representation):
+        """Modify the entry's state to match the given representation.
+
+        A PUT is just like a PATCH, except the given representation
+        must be a complete representation of the entry.
+        """
+        changeset, error = self.processAsJSONHash(media_type, representation)
+        if error is not None:
+            return error
+
+        # Make sure the representation includes values for all
+        # writable attributes.
+        # Get the fields ordered by name so that we always evaluate them in
+        # the same order. This is needed to predict errors when testing.
+        for name, field in getFieldsInOrder(self.entry.schema):
+            if not self.isModifiableField(field, True):
+                continue
+            field = field.bind(self.context)
+            marshaller = getMultiAdapter((field, self.request),
+                                         IFieldMarshaller)
+            repr_name = marshaller.representation_name
+            if (changeset.get(repr_name) is None
+                and getattr(self.entry, name) is not None):
+                # This entry has a value for the attribute, but the
+                # entity-body of the PUT request didn't make any assertion
+                # about the attribute. The resource's behavior under HTTP
+                # is undefined; we choose to send an error.
+                self.request.response.setStatus(400)
+                return ("You didn't specify a value for the attribute '%s'."
+                        % repr_name)
+
+        return self.applyChanges(changeset)
+
+
+    def do_PATCH(self, media_type, representation):
+        """Apply a JSON patch to the entry."""
+        changeset, error = self.processAsJSONHash(media_type, representation)
+        if error is not None:
+            return error
+        return self.applyChanges(changeset)
+
+    @property
+    def type_url(self):
+        "The URL to the resource type for this resource."
+        adapter = EntryAdapterUtility(self.entry.__class__)
+
+        return "%s#%s" % (
+            absoluteURL(self.request.publication.getApplication(
+                    self.request), self.request),
+            adapter.singular_type)
+
+    def isModifiableField(self, field, is_external_client):
+        """Returns true if this field's value can be changed.
+
+        Collection fields, and fields that are not part of the web
+        service interface, are never modifiable. Read-only fields are
+        not modifiable by external clients.
+
+        :param is_external_client: Whether the code trying to modify
+        the field is an external client. Read-only fields cannot be
+        directly modified from external clients, but they might change
+        as side effects of other changes.
+        """
+        if (ICollectionField.providedBy(field)
+            or field.__name__.startswith('_')):
+            return False
+        if field.readonly:
+            return not is_external_client
+        return True
+
+    def _representation(self, media_type):
+        """Return a representation of this entry, of the given media type."""
+        if media_type == self.WADL_TYPE:
+            return self.toWADL().encode("utf-8")
+        elif media_type == self.JSON_TYPE:
+            return simplejson.dumps(self, cls=ResourceJSONEncoder)
+        elif media_type == self.XHTML_TYPE:
+            return self.toXHTML().encode("utf-8")
+        else:
+            raise AssertionError(
+                    "No representation implementation for media type %s"
+                    % media_type)
 
 
 class CollectionResource(ReadOnlyResource, BatchingResourceMixin,

=== modified file 'src/lazr/restful/configure.zcml'
--- src/lazr/restful/configure.zcml	2009-03-26 17:25:22 +0000
+++ src/lazr/restful/configure.zcml	2009-06-02 16:04:54 +0000
@@ -133,6 +133,14 @@
 
     <adapter factory="lazr.restful.JSONItem" />
 
+    <!-- Adapter for URL generation -->
+    <adapter
+        for="lazr.restful.interfaces.IEntryField
+             zope.publisher.interfaces.http.IHTTPApplicationRequest"
+        provides="zope.traversing.browser.interfaces.IAbsoluteURL"
+        factory="zope.traversing.browser.AbsoluteURL"
+        />
+
     <!-- Field resources -->
     <adapter
         for="lazr.restful.interfaces.IEntryField

=== modified file 'src/lazr/restful/example/tests/field.txt'
--- src/lazr/restful/example/tests/field.txt	2009-04-06 16:57:08 +0000
+++ src/lazr/restful/example/tests/field.txt	2009-06-02 16:04:54 +0000
@@ -1,7 +1,8 @@
 = Field resources =
 
-It's possible to get the value of one particular field. You can get a
-JSON or XHTML-fragment representation.
+Each of an entry's fields has its own HTTP resource. If you only need
+to change one of an entry's fields, you can send PUT or PATCH to the
+field resource itself, rather than PUT/PATCH to the entry.
 
     >>> from lazr.restful.testing.webservice import CookbookWebServiceCaller
     >>> webservice = CookbookWebServiceCaller()
@@ -13,17 +14,38 @@
     >>> import simplejson
     >>> def set_description(description):
     ...     """Sets the description for "The Joy of Cooking"."""
-    ...     representation = {'description': description}
-    ...     ignore = webservice(cookbook_url, 'PATCH',
-    ...                         simplejson.dumps(representation))
+    ...     return webservice(field_url, 'PATCH',
+    ...                       simplejson.dumps(description)).jsonBody()
 
-    >>> set_description("<b>Bold description</b>")
+    >>> print set_description("New description")
+    New description
 
     >>> print webservice.get(field_url)
     HTTP/1.1 200 Ok
     ...
     Content-Type: application/json
     ...
+    "New description"
+
+PATCH on a field resource works identically to PUT.
+
+    >>> representation = simplejson.dumps('<b>Bold description</b>')
+    >>> print webservice.put(field_url, 'application/json',
+    ...                      representation).jsonBody()
+    <b>Bold description</b>
+
+The same rules for modifying a field apply whether you're modifying
+the entry as a whole or just modifying a single field.
+
+    >>> date_field_url = cookbook_url + "/copyright_date"
+    >>> print webservice.put(date_field_url, 'application/json',
+    ...                      simplejson.dumps("string"))
+    HTTP/1.1 400 Bad Request
+    ...
+    copyright_date: Value doesn't look like a date.
+
+Field resources also support GET, for when you only need part of an
+entry. You can get either a JSON or XHTML-fragment representation.
 
     >>> print webservice.get(field_url).jsonBody()
     <b>Bold description</b>
@@ -35,7 +57,47 @@
     ...
     &lt;b&gt;Bold description&lt;/b&gt;
 
-    >>> set_description("Description")
+Cleanup.
+
+    >>> ignored = set_description("Description")
+
+Changing a field resource can move the entry
+--------------------------------------------
+
+If you modify a field that the entry uses as part of its URL (such as
+a cookbook's name), the field's URL will change. You'll be redirected
+to the new field URL.
+
+    >>> name_url = cookbook_url + "/name"
+    >>> representation = simplejson.dumps("The Joy of Cooking Extreme")
+    >>> print webservice.put(name_url, 'application/json',
+    ...                      representation)
+    HTTP/1.1 301 Moved Permanently
+    ...
+    Location: http://.../cookbooks/The%20Joy%20of%20Cooking%20Extreme/name
+    <BLANKLINE>
+
+Note that the entry's URL has also changed.
+
+    >>> print webservice.get(cookbook_url)
+    HTTP/1.1 404 Not Found
+    ...
+
+    >>> new_cookbook_url = quote("/cookbooks/The Joy of Cooking Extreme")
+    >>> print webservice.get(new_cookbook_url)
+    HTTP/1.1 200 Ok
+    ...
+
+Cleanup.
+
+    >>> representation = simplejson.dumps("The Joy of Cooking")
+    >>> new_name_url = new_cookbook_url + "/name"
+    >>> print webservice.put(new_name_url, 'application/json',
+    ...                      representation)
+    HTTP/1.1 301 Moved Permanently
+    ...
+    Location: http://.../cookbooks/The%20Joy%20of%20Cooking/name
+    <BLANKLINE>
 
 
 = Field resources can give more detail than entry resources =
@@ -80,24 +142,21 @@
 
 = Supported methods =
 
-Field resources are read-only.
+Field resources support GET, PUT, and PATCH.
 
-    >>> for method in ['HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS']:
+    >>> for method in ['HEAD', 'POST', 'DELETE', 'OPTIONS']:
     ...     print webservice(field_url, method)
-    HTTP/1.1 405 Method Not Allowed
-    Allow: GET
-    ...
-    HTTP/1.1 405 Method Not Allowed
-    Allow: GET
-    ...
-    HTTP/1.1 405 Method Not Allowed
-    Allow: GET
-    ...
-    HTTP/1.1 405 Method Not Allowed
-    Allow: GET
-    ...
-    HTTP/1.1 405 Method Not Allowed
-    Allow: GET
+    HTTP/1.1 405 Method Not Allowed...
+    Allow: GET PUT PATCH
+    ...
+    HTTP/1.1 405 Method Not Allowed...
+    Allow: GET PUT PATCH
+    ...
+    HTTP/1.1 405 Method Not Allowed...
+    Allow: GET PUT PATCH
+    ...
+    HTTP/1.1 405 Method Not Allowed...
+    Allow: GET PUT PATCH
     ...
 
 
@@ -109,6 +168,8 @@
     >>> response = webservice.get(cookbook_url)
     >>> cookbook_etag = response._response.getHeader('ETag')
 
+<bound method BrowserResponse.getHeader of <zope.publisher.browser.BrowserResponse object at 0xa441c6c>>
+
     >>> response = webservice.get(field_url)
     >>> etag = response._response.getHeader('ETag')
 
@@ -119,13 +180,42 @@
     HTTP/1.1 304 Not Modified
     ...
 
-    >>> set_description("new description")
+    >>> ignored = set_description("new description")
     >>> print webservice.get(field_url,
     ...                      headers={'If-None-Match': etag})
     HTTP/1.1 200 Ok
     ...
 
-    >>> set_description("Description")
+=================
+Conditional write
+=================
+
+Every field supports conditional PUT and PATCH, just like the entries
+do.
+
+    >>> response = webservice.get(field_url)
+    >>> cookbook_etag = response._response.getHeader('ETag')
+
+The first attempt to modify the field succeeds, because the ETag
+provided in If-Match is the one we just got from a GET request.
+
+    >>> representation = simplejson.dumps("New description")
+    >>> print webservice.put(field_url, 'application/json',
+    ...                      representation,
+    ...                      headers={'If-Match': cookbook_etag})
+    HTTP/1.1 209 Content Returned
+    ...
+
+But when the field is modified, the ETag changes. Any subsequent
+requests that use that ETag in If-Match will fail.
+
+    >>> print webservice.put(field_url, 'application/json',
+    ...                      representation,
+    ...                      headers={'If-Match': cookbook_etag})
+    HTTP/1.1 412 Precondition Failed
+    ...
+
+    >>> ignored = set_description("Description")
 
 
 = Custom XHTML representations =
@@ -209,14 +299,14 @@
 Compare the HTML generated by the custom renderer, to the XHTML
 generated now that the default adapter is back in place.
 
-  >>> set_description("<b>Bold description</b>")
+  >>> ignored = set_description("<b>Bold description</b>")
 
   >>> print webservice.get(field_url, 'application/xhtml+xml')
   HTTP/1.1 200 Ok
   ...
   &lt;b&gt;Bold description&lt;/b&gt;
 
-  >>> set_description("Description")
+  >>> ignored = set_description("Description")
 
 The default renderer escapes HTML tags because it thinks they might
 contain XSS attacks. If you define a custom adapter, you can generate