lazr.restful

Merge lp:~leonardr/lazr.restful/simple-root into lp:lazr.restful

simple-root
Merge into trunk

Proposed by Leonard Richardson on 2009-08-11

Status:	Merged
Approved by:	Barry Warsaw on 2009-08-11
Approved revision:	53
Merged at revision:	not available
Proposed branch:	lp:~leonardr/lazr.restful/simple-root
Merge into:	lp:lazr.restful
Diff against target:	None lines
To merge this branch:	bzr merge lp:~leonardr/lazr.restful/simple-root
Related bugs:	Link a bug report

Reviewer	Review Type	Date Requested	Status
Barry Warsaw		2009-08-11	Approve on 2009-08-11
Review via email: mp+9988@code.launchpad.net

Revision history for this message

Leonard Richardson (leonardr) wrote on 2009-08-11:

The default ServiceRootResource has a very complicated implementation of getTopLevelPublications(). It goes through all the registered adapters and sees which ones are adapters for utilities, and which ones are adapters for ITopLevelEntryLink. The most obvious effect of this is that you have to register all your collections as Zope utilities.

This is fine for Launchpad, because Launchpad's collections are already registered as Zope utilities. But other web services don't do this. To take an extreme example, the WSGI example web service defines its entire object model within the root resource. So why not

I created a class called SimpleRootResource which asks its subclasses for two data structures: one for top-level collections and one for top-level entry links. It uses this data structure to drive both getTopLevelPublications() and the get() method used by TraverseWithGet. The data structure is a little bit complicated, but a SimpleRootResource subclass is significantly less complicated than the corresponding ServiceRootResource. The WSGI sample application now has much less code and a little bit less ZCML.

To get this to work without circular references, I had to move some classes around. I ended up moving all the "simple implementation of complex zope/lazr.restful feature x" classes into lazr.restful.simple. It now contains SimplePublicationMixin, SimplePublication, TraverseWithGet, SimpleRequest, and SimpleWebServiceRootResource. Most of the code in this branch is this new file + changes to the import statements in other files.

Revision history for this message

Leonard Richardson (leonardr) wrote on 2009-08-11:

"So why not" should have been "So why not create an implementation of IWebServiceRootResource that caters to simpler cases?"

Revision history for this message

Leonard Richardson (leonardr) wrote on 2009-08-11:

At Gary's suggestion, I removed 'Simple' from the name of all classes now found in lazr.restful.simple.

lp:~leonardr/lazr.restful/simple-root updated on 2009-08-11

52. By Leonard Richardson on 2009-08-11: Removed 'Simple' from the class names of classes in lazr.restful.simple.

Revision history for this message

Barry Warsaw (barry) wrote on 2009-08-11:

On Aug 11, 2009, at 06:37 PM, Leonard Richardson wrote:

>At Gary's suggestion, I removed 'Simple' from the name of all classes now found in lazr.restful.simple.

Great suggestion. I'm still reviewing the branch but will keep this in mind.
Thanks for making this change.

lp:~leonardr/lazr.restful/simple-root updated on 2009-08-11

53. By Leonard Richardson on 2009-08-11: Renamed SimpleWebServiceRootResource to RootResource.

Revision history for this message

Barry Warsaw (barry) wrote on 2009-08-11:

Download full text (15.1 KiB)

On Aug 11, 2009, at 06:15 PM, Leonard Richardson wrote:

>Leonard Richardson has proposed merging lp:~leonardr/lazr.restful/simple-root into lp:lazr.restful.
>
>Requested reviews:
> LAZR Developers (lazr-developers)
>
>The default ServiceRootResource has a very complicated implementation of getTopLevelPublications(). It goes through all the registered adapters and sees which ones are adapters for utilities, and which ones are adapters for ITopLevelEntryLink. The most obvious effect of this is that you have to register all your collections as Zope utilities.
>
>This is fine for Launchpad, because Launchpad's collections are already registered as Zope utilities. But other web services don't do this. To take an extreme example, the WSGI example web service defines its entire object model within the root resource. So why not
>
>I created a class called SimpleRootResource which asks its subclasses for two data structures: one for top-level collections and one for top-level entry links. It uses this data structure to drive both getTopLevelPublications() and the get() method used by TraverseWithGet. The data structure is a little bit complicated, but a SimpleRootResource subclass is significantly less complicated than the corresponding ServiceRootResource. The WSGI sample application now has much less code and a little bit less ZCML.
>
>To get this to work without circular references, I had to move some classes around. I ended up moving all the "simple implementation of complex zope/lazr.restful feature x" classes into lazr.restful.simple. It now contains SimplePublicationMixin, SimplePublication, TraverseWithGet, SimpleRequest, and SimpleWebServiceRootResource. Most of the code in this branch is this new file + changes to the import statements in other files.

Hi Leonard,

It's great to see the work you're doing on simplifying lazr.restful for simple
applications. The more I use lazr.restful the more I like it, and I think
it's really going to help drive up adoption by making it easier to use. I'm
going to be attending my local Python users group meeting and overwhelmingly,
people want me to do a presentation on lazr.restful.

I've deleted the chunks that look fine to me. All my other comments are
fairly trivial. Great branch, r=me.

review approve
status approve

=== modified file 'src/lazr/restful/example/wsgi/README.txt'
--- src/lazr/restful/example/wsgi/README.txt 2009-08-03 13:12:20 +0000
+++ src/lazr/restful/example/wsgi/README.txt 2009-08-11 17:47:07 +0000
> @@ -109,12 +109,11 @@
> Utilities
> =========
>
> -The service root, the top-level collection of key-value pairs, and the
> -the web service configuration object are all registered as Zope
> -utilities. A Zope utility is basically a singleton. These three
> -classes are registered as singletons because from time to time,
> -lazr.restful needs access to a canonical instance of one of these
> -classes.
> +The service root and the the web service configuration object are both

s/the the/the/

> +registered as Zope utilities. A Zope utility is basically a
> +singleton. These two classes are registered as singletons because
> +from time to time, lazr.restful needs access to a c...

On Aug 11, 2009, at 06:15 PM, Leonard Richardson wrote:

>Leonard Richardson has proposed merging lp:~leonardr/lazr.restful/simple-root into lp:lazr.restful.
>
>Requested reviews:
>    LAZR Developers (lazr-developers)
>
>The default ServiceRootResource has a very complicated implementation of getTopLevelPublications(). It goes through all the registered adapters and sees which ones are adapters for utilities, and which ones are adapters for ITopLevelEntryLink. The most obvious effect of this is that you have to register all your collections as Zope utilities.
>
>This is fine for Launchpad, because Launchpad's collections are already registered as Zope utilities. But other web services don't do this. To take an extreme example, the WSGI example web service defines its entire object model within the root resource. So why not 
>
>I created a class called SimpleRootResource which asks its subclasses for two data structures: one for top-level collections and one for top-level entry links. It uses this data structure to drive both getTopLevelPublications() and the get() method used by TraverseWithGet. The data structure is a little bit complicated, but a SimpleRootResource subclass is significantly less complicated than the corresponding ServiceRootResource. The WSGI sample application now has much less code and a little bit less ZCML.
>
>To get this to work without circular references, I had to move some classes around. I ended up moving all the "simple implementation of complex zope/lazr.restful feature x" classes into lazr.restful.simple. It now contains SimplePublicationMixin, SimplePublication, TraverseWithGet, SimpleRequest, and SimpleWebServiceRootResource. Most of the code in this branch is this new file + changes to the import statements in other files.

Hi Leonard,

It's great to see the work you're doing on simplifying lazr.restful for simple
applications.  The more I use lazr.restful the more I like it, and I think
it's really going to help drive up adoption by making it easier to use.  I'm
going to be attending my local Python users group meeting and overwhelmingly,
people want me to do a presentation on lazr.restful.

I've deleted the chunks that look fine to me.  All my other comments are
fairly trivial.  Great branch, r=me.

review approve
 status approve

=== modified file 'src/lazr/restful/example/wsgi/README.txt'
--- src/lazr/restful/example/wsgi/README.txt	2009-08-03 13:12:20 +0000
+++ src/lazr/restful/example/wsgi/README.txt	2009-08-11 17:47:07 +0000
> @@ -109,12 +109,11 @@
>  Utilities
>  =========
>  
> -The service root, the top-level collection of key-value pairs, and the
> -the web service configuration object are all registered as Zope
> -utilities. A Zope utility is basically a singleton. These three
> -classes are registered as singletons because from time to time,
> -lazr.restful needs access to a canonical instance of one of these
> -classes.
> +The service root and the the web service configuration object are both

s/the the/the/

> +registered as Zope utilities. A Zope utility is basically a
> +singleton. These two classes are registered as singletons because
> +from time to time, lazr.restful needs access to a canonical instance
> +of one of these classes.
>  
>  Utilities are registered in lazr/restful/example/wsgi/configure.zcml,
>  and each one is associated with a Zope interface. So the root resource
> @@ -123,10 +122,6 @@
>  that passes an interface class into getUtility(), that code is getting
>  the singleton utility registered for that interface.
>  
> -All top-level objects published by a lazr.restful web service must be
> -registered as utilities. This is why the set of key-value pairs is
> -registered as a utility for IPairSet.
> -
>  Traversal
>  =========
>

=== modified file 'src/lazr/restful/example/wsgi/root.py'
--- src/lazr/restful/example/wsgi/root.py	2009-07-21 15:21:35 +0000
+++ src/lazr/restful/example/wsgi/root.py	2009-08-11 16:40:43 +0000
> @@ -9,41 +9,24 @@
>  
>  from zope.component import adapts, getUtility
>  from zope.interface import implements
> -from zope.publisher.interfaces.browser import IDefaultBrowserLayer
>  from zope.traversing.browser.interfaces import IAbsoluteURL
>  
> -from lazr.restful import ServiceRootResource
> -from lazr.restful.example.wsgi.resources import IPairSet, KeyValuePair
> -from lazr.restful.interfaces import (
> -    ICollection, IServiceRootResource, IWebServiceConfiguration)
> -from lazr.restful.publisher import TraverseWithGet, WebServiceRequestTraversal
> -
> -
> -class WSGIExampleWebServiceRootResource(ServiceRootResource, TraverseWithGet):
> +from lazr.restful.example.wsgi.resources import (
> +    IKeyValuePair, PairSet, KeyValuePair)
> +from lazr.restful.interfaces import IWebServiceConfiguration
> +from lazr.restful.simple import SimpleServiceRootResource
> +from lazr.restful.publisher import WebServiceRequestTraversal
> +
> +
> +class WSGIExampleWebServiceRootResource(SimpleServiceRootResource):
>      """The root resource for the WSGI example web service."""
> -    implements (IServiceRootResource)
> -
> -    @property
> -    def top_level_names(self):
> -        return self.top_level_objects.keys()
> -
> -    def get(self, name):
> -        """Traverse to a top-level object."""
> -        return self.top_level_objects.get(name)
> -
> -    @property
> -    def top_level_objects(self):
> -        """Access or create the list of top-level objects."""
> -
> -        if getattr(self, '_top_level_objects', None) is None:
> -            pairs = [KeyValuePair(self, "foo", "bar"),
> -                     KeyValuePair(self, "1", "2")]
> -            pairset = getUtility(IPairSet)
> -            pairset.pairs = pairs
> -            self._top_level_objects = {
> -                'pairs': pairset,
> -            }
> -        return self._top_level_objects
> +
> +    def _build_top_level_objects(self):
> +        pairset = PairSet()
> +        pairset.pairs = [KeyValuePair(self, "foo", "bar"),
> +                         KeyValuePair(self, "1", "2")]
> +        collections = {'pairs': (IKeyValuePair, pairset)}
> +        return collections, {}

How about coding it like this?

pairset.pairs = [
        KeyValuePair(self, 'foo', 'bar'),
        KeyValuePair(self, '1', '2'),
        ]
    collections = dict(pairs=(IKeyValuePair, pairset))

>  
>  
>  class WSGIExampleWebServiceRootAbsoluteURL:

=== added file 'src/lazr/restful/simple.py'
--- src/lazr/restful/simple.py	1970-01-01 00:00:00 +0000
+++ src/lazr/restful/simple.py	2009-08-11 17:55:34 +0000
> @@ -0,0 +1,226 @@
> +"""Simple implementations of various Zope and lazr.restful interfaces."""
> +
> +__metaclass__ = type
> +__all__ = [
> +    'SimplePublicationMixin',
> +    'SimplePublication',
> +    'TraverseWithGet',
> +    'SimpleRequest',
> +    'SimpleWebServiceRootResource'

Alphabetize; and please end the last line with a trailing comma.

> +    ]
> +
> +import urllib
> +
> +from zope.component import queryMultiAdapter
> +from zope.interface import implements
> +from zope.publisher.browser import BrowserRequest
> +from zope.publisher.interfaces import IPublication, IPublishTraverse, NotFound
> +from zope.publisher.publish import mapply
> +from zope.security.management import endInteraction, newInteraction
> +
> +from lazr.restful import EntryAdapterUtility, ServiceRootResource
> +from lazr.restful.interfaces import ITraverseWithGet, IWebServiceLayer
> +from lazr.restful.publisher import (
> +    WebServicePublicationMixin, WebServiceRequestTraversal)
> +
> +class SimplePublicationMixin(object):
> +    """A very simple implementation of `IPublication`.
> +
> +    The object passed to the constructor is returned by getApplication().
> +    """
> +    implements(IPublication)
> +
> +    def __init__(self, application):
> +        """Create the test publication.
> +
> +        The object at which traversal should start is passed as parameter.
> +        """
> +        self.application = application
> +
> +    def beforeTraversal(self, request):
> +        """Sets the request as the current interaction.
> +
> +        (It also ends any previous interaction, that's convenient when
> +        tests don't go through the whole request.)
> +        """
> +        endInteraction()
> +        newInteraction(request)
> +
> +    def getApplication(self, request):
> +        """Returns the application passed to the constructor."""
> +        return self.application
> +
> +    def callTraversalHooks(self, request, ob):
> +        """Does nothing."""
> +
> +    def traverseName(self, request, ob, name):
> +        """Traverse by looking for an `IPublishTraverse` adapter."""
> +        # XXX flacoste 2009/03/06 bug=338831. This is copied from
> +        # zope.app.publication.publicationtraverse.PublicationTraverse.
> +        # This should really live in zope.publisher, we are copying because
> +        # we don't want to depend on zope.app stuff.
> +        # Namespace support was dropped.
> +        if name == '.':
> +            return ob
> +
> +        if IPublishTraverse.providedBy(ob):
> +            ob2 = ob.publishTraverse(request, name)
> +        else:
> +            # self is marker.
> +            adapter = queryMultiAdapter(
> +                (ob, request), IPublishTraverse, default=self)
> +            if adapter is not self:
> +                ob2 = adapter.publishTraverse(request, name)
> +            else:
> +                raise NotFound(ob, name, request)
> +
> +        return self.wrapTraversedObject(ob2)
> +
> +    def wrapTraversedObject(self, ob):
> +        """Wrap the traversed object, for instance in a security proxy.
> +
> +        By default, does nothing."""
> +        return ob
> +
> +    def afterTraversal(self, request, ob):
> +        """Does nothing."""
> +
> +    def callObject(self, request, ob):
> +        """Call the object, returning the result."""
> +        return mapply(ob, request.getPositionalArguments(), request)
> +
> +    def afterCall(self, request, ob):
> +        """Does nothing."""
> +
> +    def handleException(self, object, request, exc_info, retry_allowed=1):
> +        """Prints the exception."""
> +        # Reproduce the behavior of ZopePublication by looking up a view
> +        # for this exception.
> +        exception = exc_info[1]
> +        view = queryMultiAdapter((exception, request), name='index.html')
> +        if view is not None:
> +            exc_info = None

I was looking at my code for this and I had to scratch my head at it.  I
actually don't think this line is needed since exc_info is never used in this
branch again.

> +            request.response.reset()
> +            request.response.setResult(view())
> +        else:
> +            traceback.print_exception(*exc_info)
> +
> +    def endRequest(self, request, ob):
> +        """Ends the interaction."""
> +        endInteraction()
> +
> +
> +class SimplePublication(WebServicePublicationMixin, SimplePublicationMixin):
> +    """A simple publication.
> +
> +    Combines the IPublication implementation of SimplePublicationMixin
> +    with the web service implementation of WebServicePublicationMixin,
> +    """
> +    pass
> +
> +
> +class TraverseWithGet(object):
> +    """An implementation of `IPublishTraverse` that uses the get() method.
> +
> +    This is a simple traversal technique that works with any object
> +    that defines a lookup method called get().
> +
> +    This class should not be confused with
> +    WebServiceRequestTraversal. This class (or any other class that
> +    implements IPublishTraverse) controls traversal in the web
> +    application towards an object that implements IEntry. Once an
> +    IEntry has been found, further traversal (eg. to scoped
> +    collections or fields) always happens with
> +    WebServiceRequestTraversal.
> +    """
> +    implements(ITraverseWithGet)
> +
> +    def publishTraverse(self, request, name):
> +        """See `IPublishTraverse`."""
> +        name = urllib.unquote(name)
> +        value = self.get(name)
> +        if value is None:
> +            raise NotFound(self, name)
> +        return value
> +
> +    def get(self, name):
> +        """See `ITraverseWithGet`."""
> +        raise NotImplementedError
> +
> +
> +class SimpleRequest(WebServiceRequestTraversal, BrowserRequest):
> +    """A web service request with no special features."""
> +    implements(IWebServiceLayer)
> +
> +
> +class SimpleServiceRootResource(ServiceRootResource, TraverseWithGet):
> +    """A service root that expects top-level objects to be defined in code.
> +
> +    ServiceRootResource expects top-level objects to be registered as
> +    Zope interfaces.
> +    """
> +
> +    @property
> +    def top_level_names(self):
> +        return self.top_level_objects.keys()
> +
> +    def get(self, name):
> +        """Traverse to a top-level object."""
> +        return self.top_level_objects.get(name)
> +
> +    def getTopLevelPublications(self):
> +        """Return a mapping of top-level link names to published objects."""
> +        top_level_resources = {}
> +        # First collect the top-level collections.
> +        for name, (schema_interface, obj) in (
> +            self.top_level_collections.items()):
> +            adapter = EntryAdapterUtility.forSchemaInterface(schema_interface)
> +            link_name = ("%s_collection_link" % adapter.plural_type)
> +            top_level_resources[link_name] = obj
> +        # Then collect the top-level entries.
> +        for name, entry_link in self.top_level_entry_links.items():
> +            link_name = ("%s_link" % ITopLevelEntryLink(entry_link).link_name)
> +            top_level_resources[link_name] = entry_link
> +        return top_level_resources
> +
> +    @property
> +    def top_level_objects(self):
> +        """Return this web service's top-level objects."""
> +        objects = {}
> +        for name, (schema_interface, obj) in (
> +            self.top_level_collections.items()):
> +            objects[name] = obj
> +        objects.update(self.top_level_entry_links)
> +        return objects
> +
> +    @property
> +    def top_level_collections(self):
> +        """Return this web service's top-level collections.
> +
> +        :return: A hash mapping a name to a 2-tuple (interface, collection).
> +        The interface is the kind of thing contained in the collection.
> +        """
> +        if not hasattr(self, '_top_level_collections'):
> +            self._top_level_collections, self._top_level_entry_links = (
> +                self._build_top_level_objects())
> +        return self._top_level_collections
> +
> +    @property
> +    def top_level_entry_links(self):
> +        """Return this web service's top-level entry links."""
> +        if not hasattr(self, '_top_level_entry_links'):
> +            self._top_level_collections, self._top_level_entry_links = (
> +                self._build_top_level_objects())
> +        return self._top_level_entry_links
> +
> +    def _build_top_level_objects(self):
> +        """Create the list of top-level objects.
> +
> +        :return: A 2-tuple of hashes (collections, entry_links). The
> +        'collections' hash maps a name to a 2-tuple (interface, object).
> +        The interface is the kind of thing contained in the collection.
> +        For instance, 'users': (IUser, UserSet())
> +
> +        The 'entry_links' hash maps a name to an object.
> +        """
> +        return ({}, {})

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk

Subscribers

People subscribed via source and target branches

to all changes:

Gary Poster

Launchpad code reviewers from Canonical

Leonard Richardson

lazr.restful

Merge lp:~leonardr/lazr.restful/simple-root into lp:lazr.restful

Commit message

Description of the change

Preview Diff

Subscribers

 === modified file 'src/lazr/restful/docs/webservice-marshallers.txt'
 --- src/lazr/restful/docs/webservice-marshallers.txt	2009-08-04 19:27:13 +0000
 +++ src/lazr/restful/docs/webservice-marshallers.txt	2009-08-11 16:40:43 +0000
@@ -9,7 +9,7 @@
  application root.
      >>> from lazr.restful.testing.webservice import WebServiceTestPublication
--    >>> from lazr.restful.publisher import SimpleRequest
++    >>> from lazr.restful.simple import SimpleRequest
      >>> from lazr.restful.example.root import (
      ...     CookbookServiceRootResource)
      >>> request = SimpleRequest("", {'HTTP_HOST': 'cookbooks.dev'})
 === modified file 'src/lazr/restful/docs/webservice-request.txt'
 --- src/lazr/restful/docs/webservice-request.txt	2009-08-04 18:23:18 +0000
 +++ src/lazr/restful/docs/webservice-request.txt	2009-08-11 16:40:43 +0000
@@ -14,7 +14,7 @@
      >>> from lazr.restful.publisher import (
      ...     browser_request_to_web_service_request)
      >>> from lazr.restful.testing.webservice import WebServiceTestPublication
--    >>> from lazr.restful.publisher import SimpleRequest
++    >>> from lazr.restful.simple import SimpleRequest
      >>> from zope.interface import implements
      >>> from zope.component import getSiteManager
      >>> from zope.publisher.browser import TestRequest
 === modified file 'src/lazr/restful/docs/webservice.txt'
 --- src/lazr/restful/docs/webservice.txt	2009-08-04 20:21:42 +0000
 +++ src/lazr/restful/docs/webservice.txt	2009-08-11 16:40:43 +0000
@@ -512,7 +512,7 @@
      >>> from lazr.restful.interfaces import IWebServiceConfiguration
      >>> from lazr.restful.testing.webservice import WebServiceTestPublication
--    >>> from lazr.restful.publisher import SimpleRequest
++    >>> from lazr.restful.simple import SimpleRequest
      >>> from cStringIO import StringIO
 === modified file 'src/lazr/restful/example/configuration.py'
 --- src/lazr/restful/example/configuration.py	2009-08-04 18:23:18 +0000
 +++ src/lazr/restful/example/configuration.py	2009-08-11 16:40:43 +0000
@@ -12,7 +12,7 @@
  from lazr.restful.interfaces import (
      IServiceRootResource, IWebServiceConfiguration)
--from lazr.restful.publisher import SimpleRequest
++from lazr.restful.simple import SimpleRequest
  from lazr.restful.testing.webservice import WebServiceTestPublication
  class CookbookWebServiceConfiguration:
 === modified file 'src/lazr/restful/example/wsgi/README.txt'
 --- src/lazr/restful/example/wsgi/README.txt	2009-08-03 13:12:20 +0000
 +++ src/lazr/restful/example/wsgi/README.txt	2009-08-11 17:47:07 +0000
@@ -52,17 +52,21 @@
  Every lazr.restful web service needs a root resource. The root must
  implement the Zope interface
  lazr.restful.interfaces.IServiceRootResource. The easiest way to do
--this is to subclass lazr.restful.ServiceRootResource and implement
--top_level_names, which advertises the main features of your web
--service to your users. The service root resource must be registered as
--a utility for IServiceRootResource (see "Utilities" below).
++this is to subclass lazr.restful.simple.SimpleWebServiceRootResource
++and implement _build_top_level_objects(), which advertises the main
++features of your web service to your users. The service root resource
++must be registered as a utility for IServiceRootResource (see
++"Utilities" below).
  Our service root resource is
--lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootResource.
--
--We only have one top-level object, the collection of key-value pairs, so
--this implementation of top_level_names ends up returning
--['pairs'].
++lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootResource. We
++only have one top-level object, the collection of key-value pairs, so
++this implementation of _build_top_level_objects() just returns
++'pairs'. It maps 'pairs' to a 2-tuple (IKeyValuePair, pairset). Here,
++"pairset" is the collection of key-value pairs itself, and
++IKeyValuePair is a Zope interface class that explains what kind of
++object is found in the collection. You'll see IKeyValuePair again in
++the next section of this document.
  The top-level collection
  ------------------------
@@ -84,10 +88,6 @@
  Then we define the implementation (PairSet), which implements
  getPairs().
--Like all top-level collections, the collection of key-value pairs is
--registered as a utility. In this case, PairSet is registered as the
--utility for IPairSet (see "Utilities" below).
--
  The entry resource
  ------------------
@@ -109,12 +109,11 @@
  Utilities
  =========
--The service root, the top-level collection of key-value pairs, and the
--the web service configuration object are all registered as Zope
--utilities. A Zope utility is basically a singleton. These three
--classes are registered as singletons because from time to time,
--lazr.restful needs access to a canonical instance of one of these
--classes.
++The service root and the the web service configuration object are both
++registered as Zope utilities. A Zope utility is basically a
++singleton. These two classes are registered as singletons because
++from time to time, lazr.restful needs access to a canonical instance
++of one of these classes.
  Utilities are registered in lazr/restful/example/wsgi/configure.zcml,
  and each one is associated with a Zope interface. So the root resource
@@ -123,10 +122,6 @@
  that passes an interface class into getUtility(), that code is getting
  the singleton utility registered for that interface.
--All top-level objects published by a lazr.restful web service must be
--registered as utilities. This is why the set of key-value pairs is
--registered as a utility for IPairSet.
--
  Traversal
  =========
@@ -151,7 +146,11 @@
    (lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootResource)
 . "pairs" is passed into WSGIExampleWebServiceRootResource.get(), and
--   the result is the lazr.restful.example.wsgi.resources.PairSet object.
++   the result is the lazr.restful.example.wsgi.resources.PairSet
++   object. (The get() implementation is inherited from
++   SimpleWebServiceRootResource. It works because our implementation
++   of _build_top_level_objects returned a dictionary that had a key
++   called "pairs".)
 . There are no more path fragments, so traversal is complete. The
     PairSet object will be published as a collection resource. Why a
 === modified file 'src/lazr/restful/example/wsgi/configure.zcml'
 --- src/lazr/restful/example/wsgi/configure.zcml	2009-08-04 19:27:13 +0000
 +++ src/lazr/restful/example/wsgi/configure.zcml	2009-08-11 15:26:14 +0000
@@ -22,11 +22,6 @@
      provides="lazr.restful.interfaces.IServiceRootResource"
      factory="lazr.restful.example.wsgi.root.WSGIExampleWebServiceRootResource" />
--  <!--All top-level objects need to be registered as utilities.-->
--  <utility
--    provides="lazr.restful.example.wsgi.resources.IPairSet"
--    factory="lazr.restful.example.wsgi.resources.PairSet" />
--
    <!--The configuration object also needs to be registered as a utility.-->
    <utility
      factory="lazr.restful.example.wsgi.configuration.WSGIExampleWebServiceConfiguration"
 === modified file 'src/lazr/restful/example/wsgi/resources.py'
 --- src/lazr/restful/example/wsgi/resources.py	2009-08-03 13:12:20 +0000
 +++ src/lazr/restful/example/wsgi/resources.py	2009-08-11 16:40:43 +0000
@@ -14,7 +14,8 @@
      collection_default_content, export_as_webservice_collection,
      export_as_webservice_entry, exported)
  from lazr.restful.interfaces import IServiceRootResource
--from lazr.restful.publisher import TraverseWithGet
++from lazr.restful.simple import TraverseWithGet
++
  class IKeyValuePair(ILocation):
      export_as_webservice_entry()
 === modified file 'src/lazr/restful/example/wsgi/root.py'
 --- src/lazr/restful/example/wsgi/root.py	2009-07-21 15:21:35 +0000
 +++ src/lazr/restful/example/wsgi/root.py	2009-08-11 16:40:43 +0000
@@ -9,41 +9,24 @@
  from zope.component import adapts, getUtility
  from zope.interface import implements
--from zope.publisher.interfaces.browser import IDefaultBrowserLayer
  from zope.traversing.browser.interfaces import IAbsoluteURL
--from lazr.restful import ServiceRootResource
--from lazr.restful.example.wsgi.resources import IPairSet, KeyValuePair
--from lazr.restful.interfaces import (
--    ICollection, IServiceRootResource, IWebServiceConfiguration)
--from lazr.restful.publisher import TraverseWithGet, WebServiceRequestTraversal
--
--
--class WSGIExampleWebServiceRootResource(ServiceRootResource, TraverseWithGet):
++from lazr.restful.example.wsgi.resources import (
++    IKeyValuePair, PairSet, KeyValuePair)
++from lazr.restful.interfaces import IWebServiceConfiguration
++from lazr.restful.simple import SimpleServiceRootResource
++from lazr.restful.publisher import WebServiceRequestTraversal
++
++
++class WSGIExampleWebServiceRootResource(SimpleServiceRootResource):
      """The root resource for the WSGI example web service."""
--    implements (IServiceRootResource)
--
--    @property
--    def top_level_names(self):
--        return self.top_level_objects.keys()
--
--    def get(self, name):
--        """Traverse to a top-level object."""
--        return self.top_level_objects.get(name)
--
--    @property
--    def top_level_objects(self):
--        """Access or create the list of top-level objects."""
--
--        if getattr(self, '_top_level_objects', None) is None:
--            pairs = [KeyValuePair(self, "foo", "bar"),
--                     KeyValuePair(self, "1", "2")]
--            pairset = getUtility(IPairSet)
--            pairset.pairs = pairs
--            self._top_level_objects = {
--                'pairs': pairset,
--            }
--        return self._top_level_objects
++
++    def _build_top_level_objects(self):
++        pairset = PairSet()
++        pairset.pairs = [KeyValuePair(self, "foo", "bar"),
++                         KeyValuePair(self, "1", "2")]
++        collections = {'pairs': (IKeyValuePair, pairset)}
++        return collections, {}
  class WSGIExampleWebServiceRootAbsoluteURL:
 === modified file 'src/lazr/restful/example/wsgi/tests/test_integration.py'
 --- src/lazr/restful/example/wsgi/tests/test_integration.py	2009-08-04 15:59:15 +0000
 +++ src/lazr/restful/example/wsgi/tests/test_integration.py	2009-08-11 16:40:43 +0000
@@ -16,7 +16,7 @@
  from lazr.restful.example.wsgi.root import WSGIExampleWebServiceRootResource
  from lazr.restful.interfaces import IWebServiceConfiguration
--from lazr.restful.publisher import SimplePublication
++from lazr.restful.simple import SimplePublication
  from lazr.restful.testing.webservice import WebServiceApplication
 === modified file 'src/lazr/restful/example/wsgi/webservice.py'
 --- src/lazr/restful/example/wsgi/webservice.py	2009-08-04 18:23:18 +0000
 +++ src/lazr/restful/example/wsgi/webservice.py	2009-08-11 16:40:43 +0000
@@ -17,7 +17,7 @@
  from lazr.restful.interfaces import IWebServiceConfiguration
--from lazr.restful.publisher import SimplePublication, SimpleRequest
++from lazr.restful.simple import SimplePublication, SimpleRequest
  from lazr.restful.example.wsgi.root import WSGIExampleWebServiceRootResource
 === modified file 'src/lazr/restful/publisher.py'
 --- src/lazr/restful/publisher.py	2009-08-04 22:26:53 +0000
 +++ src/lazr/restful/publisher.py	2009-08-11 16:40:43 +0000
@@ -9,8 +9,6 @@
  __metaclass__ = type
  __all__ = [
      'browser_request_to_web_service_request',
--    'SimplePublication',
--    'SimpleRequest',
      'TraverseWithGet',
      'WebServicePublicationMixin',
      'WebServiceRequestTraversal',
@@ -23,23 +21,20 @@
  from zope.component import (
      adapter, getMultiAdapter, getUtility, queryAdapter, queryMultiAdapter)
  from zope.interface import alsoProvides, implementer, implements
--from zope.publisher.browser import BrowserRequest
--from zope.publisher.interfaces import IPublication, IPublishTraverse, NotFound
++from zope.publisher.interfaces import NotFound
  from zope.publisher.interfaces.browser import IBrowserRequest
--from zope.publisher.publish import mapply
  from zope.schema.interfaces import IBytes, IObject
  from zope.security.checker import ProxyFactory
--from zope.security.management import endInteraction, newInteraction
  from lazr.uri import URI
  from lazr.restful import (
--    CollectionResource, EntryField, EntryFieldResource, EntryResource,
--    ScopedCollection)
++    CollectionResource, EntryField, EntryFieldResource,
++    EntryResource, ScopedCollection, ServiceRootResource)
  from lazr.restful.interfaces import (
      IByteStorage, ICollection, ICollectionField, IEntry, IEntryField,
--    IHTTPResource, ITraverseWithGet, IWebBrowserInitiatedRequest,
--    IWebServiceClientRequest, IWebServiceConfiguration, IWebServiceLayer)
++    IHTTPResource, IWebBrowserInitiatedRequest,
++    IWebServiceClientRequest, IWebServiceConfiguration)
  class WebServicePublicationMixin:
@@ -190,131 +185,6 @@
          return value
--class SimplePublicationMixin(object):
--    """A very simple implementation of `IPublication`.
--
--    The object passed to the constructor is returned by getApplication().
--    """
--    implements(IPublication)
--
--    def __init__(self, application):
--        """Create the test publication.
--
--        The object at which traversal should start is passed as parameter.
--        """
--        self.application = application
--
--    def beforeTraversal(self, request):
--        """Sets the request as the current interaction.
--
--        (It also ends any previous interaction, that's convenient when
--        tests don't go through the whole request.)
--        """
--        endInteraction()
--        newInteraction(request)
--
--    def getApplication(self, request):
--        """Returns the application passed to the constructor."""
--        return self.application
--
--    def callTraversalHooks(self, request, ob):
--        """Does nothing."""
--
--    def traverseName(self, request, ob, name):
--        """Traverse by looking for an `IPublishTraverse` adapter."""
--        # XXX flacoste 2009/03/06 bug=338831. This is copied from
--        # zope.app.publication.publicationtraverse.PublicationTraverse.
--        # This should really live in zope.publisher, we are copying because
--        # we don't want to depend on zope.app stuff.
--        # Namespace support was dropped.
--        if name == '.':
--            return ob
--
--        if IPublishTraverse.providedBy(ob):
--            ob2 = ob.publishTraverse(request, name)
--        else:
--            # self is marker.
--            adapter = queryMultiAdapter(
--                (ob, request), IPublishTraverse, default=self)
--            if adapter is not self:
--                ob2 = adapter.publishTraverse(request, name)
--            else:
--                raise NotFound(ob, name, request)
--
--        return self.wrapTraversedObject(ob2)
--
--    def wrapTraversedObject(self, ob):
--        """Wrap the traversed object, for instance in a security proxy.
--
--        By default, does nothing."""
--        return ob
--
--    def afterTraversal(self, request, ob):
--        """Does nothing."""
--
--    def callObject(self, request, ob):
--        """Call the object, returning the result."""
--        return mapply(ob, request.getPositionalArguments(), request)
--
--    def afterCall(self, request, ob):
--        """Does nothing."""
--
--    def handleException(self, object, request, exc_info, retry_allowed=1):
--        """Prints the exception."""
--        # Reproduce the behavior of ZopePublication by looking up a view
--        # for this exception.
--        exception = exc_info[1]
--        view = queryMultiAdapter((exception, request), name='index.html')
--        if view is not None:
--            exc_info = None
--            request.response.reset()
--            request.response.setResult(view())
--        else:
--            traceback.print_exception(*exc_info)
--
--    def endRequest(self, request, ob):
--        """Ends the interaction."""
--        endInteraction()
--
--
--class SimplePublication(WebServicePublicationMixin, SimplePublicationMixin):
--    """A simple publication.
--
--    Combines the IPublication implementation of SimplePublicationMixin
--    with the web service implementation of WebServicePublicationMixin,
--    """
--    pass
--
--
--class TraverseWithGet(object):
--    """An implementation of `IPublishTraverse` that uses the get() method.
--
--    This is a simple traversal technique that works with any object
--    that defines a lookup method called get().
--
--    This class should not be confused with
--    WebServiceRequestTraversal. This class (or any other class that
--    implements IPublishTraverse) controls traversal in the web
--    application towards an object that implements IEntry. Once an
--    IEntry has been found, further traversal (eg. to scoped
--    collections or fields) always happens with
--    WebServiceRequestTraversal.
--    """
--    implements(ITraverseWithGet)
--
--    def publishTraverse(self, request, name):
--        """See `IPublishTraverse`."""
--        name = urllib.unquote(name)
--        value = self.get(name)
--        if value is None:
--            raise NotFound(self, name)
--        return value
--
--    def get(self, name):
--        """See `ITraverseWithGet`."""
--        raise NotImplementedError
--
--
  class WebServiceRequestTraversal(object):
      """Mixin providing web-service resource wrapping in traversal.
@@ -370,11 +240,6 @@
          return None
--class SimpleRequest(WebServiceRequestTraversal, BrowserRequest):
--    """A web service request with no special features."""
--    implements(IWebServiceLayer)
--
--
  @implementer(IWebServiceClientRequest)
  @adapter(IBrowserRequest)
  def browser_request_to_web_service_request(website_request):
 === added file 'src/lazr/restful/simple.py'
 --- src/lazr/restful/simple.py	1970-01-01 00:00:00 +0000
 +++ src/lazr/restful/simple.py	2009-08-11 17:55:34 +0000
@@ -0,0 +1,226 @@
++"""Simple implementations of various Zope and lazr.restful interfaces."""
++
++__metaclass__ = type
++__all__ = [
++    'SimplePublicationMixin',
++    'SimplePublication',
++    'TraverseWithGet',
++    'SimpleRequest',
++    'SimpleWebServiceRootResource'
++    ]
++
++import urllib
++
++from zope.component import queryMultiAdapter
++from zope.interface import implements
++from zope.publisher.browser import BrowserRequest
++from zope.publisher.interfaces import IPublication, IPublishTraverse, NotFound
++from zope.publisher.publish import mapply
++from zope.security.management import endInteraction, newInteraction
++
++from lazr.restful import EntryAdapterUtility, ServiceRootResource
++from lazr.restful.interfaces import ITraverseWithGet, IWebServiceLayer
++from lazr.restful.publisher import (
++    WebServicePublicationMixin, WebServiceRequestTraversal)
++
++class SimplePublicationMixin(object):
++    """A very simple implementation of `IPublication`.
++
++    The object passed to the constructor is returned by getApplication().
++    """
++    implements(IPublication)
++
++    def __init__(self, application):
++        """Create the test publication.
++
++        The object at which traversal should start is passed as parameter.
++        """
++        self.application = application
++
++    def beforeTraversal(self, request):
++        """Sets the request as the current interaction.
++
++        (It also ends any previous interaction, that's convenient when
++        tests don't go through the whole request.)
++        """
++        endInteraction()
++        newInteraction(request)
++
++    def getApplication(self, request):
++        """Returns the application passed to the constructor."""
++        return self.application
++
++    def callTraversalHooks(self, request, ob):
++        """Does nothing."""
++
++    def traverseName(self, request, ob, name):
++        """Traverse by looking for an `IPublishTraverse` adapter."""
++        # XXX flacoste 2009/03/06 bug=338831. This is copied from
++        # zope.app.publication.publicationtraverse.PublicationTraverse.
++        # This should really live in zope.publisher, we are copying because
++        # we don't want to depend on zope.app stuff.
++        # Namespace support was dropped.
++        if name == '.':
++            return ob
++
++        if IPublishTraverse.providedBy(ob):
++            ob2 = ob.publishTraverse(request, name)
++        else:
++            # self is marker.
++            adapter = queryMultiAdapter(
++                (ob, request), IPublishTraverse, default=self)
++            if adapter is not self:
++                ob2 = adapter.publishTraverse(request, name)
++            else:
++                raise NotFound(ob, name, request)
++
++        return self.wrapTraversedObject(ob2)
++
++    def wrapTraversedObject(self, ob):
++        """Wrap the traversed object, for instance in a security proxy.
++
++        By default, does nothing."""
++        return ob
++
++    def afterTraversal(self, request, ob):
++        """Does nothing."""
++
++    def callObject(self, request, ob):
++        """Call the object, returning the result."""
++        return mapply(ob, request.getPositionalArguments(), request)
++
++    def afterCall(self, request, ob):
++        """Does nothing."""
++
++    def handleException(self, object, request, exc_info, retry_allowed=1):
++        """Prints the exception."""
++        # Reproduce the behavior of ZopePublication by looking up a view
++        # for this exception.
++        exception = exc_info[1]
++        view = queryMultiAdapter((exception, request), name='index.html')
++        if view is not None:
++            exc_info = None
++            request.response.reset()
++            request.response.setResult(view())
++        else:
++            traceback.print_exception(*exc_info)
++
++    def endRequest(self, request, ob):
++        """Ends the interaction."""
++        endInteraction()
++
++
++class SimplePublication(WebServicePublicationMixin, SimplePublicationMixin):
++    """A simple publication.
++
++    Combines the IPublication implementation of SimplePublicationMixin
++    with the web service implementation of WebServicePublicationMixin,
++    """
++    pass
++
++
++class TraverseWithGet(object):
++    """An implementation of `IPublishTraverse` that uses the get() method.
++
++    This is a simple traversal technique that works with any object
++    that defines a lookup method called get().
++
++    This class should not be confused with
++    WebServiceRequestTraversal. This class (or any other class that
++    implements IPublishTraverse) controls traversal in the web
++    application towards an object that implements IEntry. Once an
++    IEntry has been found, further traversal (eg. to scoped
++    collections or fields) always happens with
++    WebServiceRequestTraversal.
++    """
++    implements(ITraverseWithGet)
++
++    def publishTraverse(self, request, name):
++        """See `IPublishTraverse`."""
++        name = urllib.unquote(name)
++        value = self.get(name)
++        if value is None:
++            raise NotFound(self, name)
++        return value
++
++    def get(self, name):
++        """See `ITraverseWithGet`."""
++        raise NotImplementedError
++
++
++class SimpleRequest(WebServiceRequestTraversal, BrowserRequest):
++    """A web service request with no special features."""
++    implements(IWebServiceLayer)
++
++
++class SimpleServiceRootResource(ServiceRootResource, TraverseWithGet):
++    """A service root that expects top-level objects to be defined in code.
++
++    ServiceRootResource expects top-level objects to be registered as
++    Zope interfaces.
++    """
++
++    @property
++    def top_level_names(self):
++        return self.top_level_objects.keys()
++
++    def get(self, name):
++        """Traverse to a top-level object."""
++        return self.top_level_objects.get(name)
++
++    def getTopLevelPublications(self):
++        """Return a mapping of top-level link names to published objects."""
++        top_level_resources = {}
++        # First collect the top-level collections.
++        for name, (schema_interface, obj) in (
++            self.top_level_collections.items()):
++            adapter = EntryAdapterUtility.forSchemaInterface(schema_interface)
++            link_name = ("%s_collection_link" % adapter.plural_type)
++            top_level_resources[link_name] = obj
++        # Then collect the top-level entries.
++        for name, entry_link in self.top_level_entry_links.items():
++            link_name = ("%s_link" % ITopLevelEntryLink(entry_link).link_name)
++            top_level_resources[link_name] = entry_link
++        return top_level_resources
++
++    @property
++    def top_level_objects(self):
++        """Return this web service's top-level objects."""
++        objects = {}
++        for name, (schema_interface, obj) in (
++            self.top_level_collections.items()):
++            objects[name] = obj
++        objects.update(self.top_level_entry_links)
++        return objects
++
++    @property
++    def top_level_collections(self):
++        """Return this web service's top-level collections.
++
++        :return: A hash mapping a name to a 2-tuple (interface, collection).
++        The interface is the kind of thing contained in the collection.
++        """
++        if not hasattr(self, '_top_level_collections'):
++            self._top_level_collections, self._top_level_entry_links = (
++                self._build_top_level_objects())
++        return self._top_level_collections
++
++    @property
++    def top_level_entry_links(self):
++        """Return this web service's top-level entry links."""
++        if not hasattr(self, '_top_level_entry_links'):
++            self._top_level_collections, self._top_level_entry_links = (
++                self._build_top_level_objects())
++        return self._top_level_entry_links
++
++    def _build_top_level_objects(self):
++        """Create the list of top-level objects.
++
++        :return: A 2-tuple of hashes (collections, entry_links). The
++        'collections' hash maps a name to a 2-tuple (interface, object).
++        The interface is the kind of thing contained in the collection.
++        For instance, 'users': (IUser, UserSet())
++
++        The 'entry_links' hash maps a name to an object.
++        """
++        return ({}, {})
 === modified file 'src/lazr/restful/testing/webservice.py'
 --- src/lazr/restful/testing/webservice.py	2009-08-04 18:23:18 +0000
 +++ src/lazr/restful/testing/webservice.py	2009-08-11 16:40:43 +0000
@@ -33,8 +33,8 @@
  from lazr.restful.interfaces import (
      IWebServiceConfiguration, IWebServiceLayer)
  from lazr.restful.publisher import (
--    SimplePublication, SimpleRequest, WebServicePublicationMixin,
--    WebServiceRequestTraversal)
++    WebServicePublicationMixin, WebServiceRequestTraversal)
++from lazr.restful.simple import SimplePublication, SimpleRequest
  from lazr.uri import URI
 === modified file 'src/lazr/restful/tests/test_webservice.py'
 --- src/lazr/restful/tests/test_webservice.py	2009-08-04 18:23:18 +0000
 +++ src/lazr/restful/tests/test_webservice.py	2009-08-11 16:40:43 +0000
@@ -20,7 +20,7 @@
      ICollection, IEntry, IEntryResource, IResourceGETOperation,
      IWebServiceClientRequest)
  from lazr.restful import EntryResource, ServiceRootResource, ResourceGETOperation
--from lazr.restful.publisher import SimpleRequest
++from lazr.restful.simple import SimpleRequest
  from lazr.restful.declarations import (
      collection_default_content, exported, export_as_webservice_collection,
      export_as_webservice_entry, export_read_operation, operation_parameters)