Merge lp:~leonardr/lazr.restful/grok-configuration-2 into lp:lazr.restful

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch defines some new grokkers for registering utilities and adapters. It gets rid of the "manually call grokcore.component methods" technique in favor of the "subclass a class, even if the subclass is empty" technique.

[Gary Poster (gary)]

Looks good.

Please add the directives to the pertinent module's __all__.

I wonder if the base classes ought to be named clearly as "Abstract" or something else. Then I would have seen

    class RootAbsoluteURL(AbstractRootAbsoluteURL):

and

    class BelowRootAbsoluteURL(AbstractAbsoluteURL):

which I think would have been clearer for me. As I mentioned on IRC, if you disagree, I'll leave it alone. That's my inclination though.

Thank you

Gary

review: Approve

=== modified file 'src/lazr/restful/directives/__init__.py'
--- src/lazr/restful/directives/__init__.py	2009-09-02 19:36:14 +0000
+++ src/lazr/restful/directives/__init__.py	2009-09-03 14:10:38 +0000
@@ -9,27 +9,55 @@
 
 import martian
 from zope.component import getSiteManager, getUtility
+from zope.location.interfaces import ILocation
+from zope.traversing.browser import AbsoluteURL
+from zope.traversing.browser.interfaces import IAbsoluteURL
+
 from lazr.restful.interfaces import (
-    IServiceRootResource, IWebServiceConfiguration)
+    IServiceRootResource, IWebServiceConfiguration, IWebServiceLayer)
+from lazr.restful import ServiceRootResource
 from lazr.restful.simple import (
-    BaseWebServiceConfiguration, Publication, Request)
+    BaseWebServiceConfiguration, Publication, Request,
+    RootResourceAbsoluteURL)
 
 
 class request_class(martian.Directive):
-    """Directive used to specify a service's request class."""
+    """Directive used to specify a service's request class.
+
+    The default is lazr.restful.simple.Request.
+    """
     scope = martian.CLASS
     store = martian.ONCE
     default = Request
 
 
 class publication_class(martian.Directive):
-    """Directive used to specify a service's publication class."""
+    """Directive used to specify a service's publication class.
+
+    The default is lazr.restful.simple.Publication.
+    """
     scope = martian.CLASS
     store = martian.ONCE
     default = Publication
 
 
 class ConfigurationGrokker(martian.ClassGrokker):
+    """Subclass BaseWebServiceConfiguration for an easy configuration class.
+
+    Subclass BaseWebServiceConfiguration and override any of the
+    configuration settings specific to your web service.
+
+    This grokker creates default implementations of createRequest()
+    and get_request_user, if those methods are not implemented.
+
+    The default implementations use the request and publication
+    classes you specify with the directives
+    lazr.restful.directives.request_class() and
+    lazr.restful.directives.publication_class().
+
+    This grokker then registers an instance of your subclass as the
+    singleton configuration object.
+    """
     martian.component(BaseWebServiceConfiguration)
     martian.directive(request_class)
     martian.directive(publication_class)
@@ -54,3 +82,36 @@
         # Register as utility.
         getSiteManager().registerUtility(cls(), IWebServiceConfiguration)
         return True
+
+
+class ServiceRootGrokker(martian.ClassGrokker):
+    """Registers your service root as a singleton object."""
+    martian.component(ServiceRootResource)
+    def execute(self, cls, config, *kw):
+        getSiteManager().registerUtility(cls(), IServiceRootResource)
+        return True
+
+
+class RootResourceAbsoluteURLGrokker(martian.ClassGrokker):
+    """Registers a strategy for generating your service's base URL.
+
+    In most cases you can simply create an empty subclass of
+    RootResourceAbsoluteURL.
+    """
+    martian.component(RootResourceAbsoluteURL)
+    def execute(self, cls, config, *kw):
+        getSiteManager().registerAdapter(cls)
+        return True
+
+
+class AbsoluteURLGrokker(martian.ClassGrokker):
+    """Registers a strategy for generating an object's URL.
+
+    In most cases you can simply create an empty subclass of
+    AbsoluteURL.
+    """
+    martian.component(AbsoluteURL)
+    def execute(self, cls, config, *kw):
+        getSiteManager().registerAdapter(
+            cls, (ILocation, IWebServiceLayer), IAbsoluteURL)
+        return True

=== modified file 'src/lazr/restful/example/base/root.py'
--- src/lazr/restful/example/base/root.py	2009-09-02 18:54:22 +0000
+++ src/lazr/restful/example/base/root.py	2009-09-03 12:40:34 +0000
@@ -350,15 +350,13 @@
 
 
 # Define classes for the service root.
-class CookbookServiceRootResource(ServiceRootResource,
-                                  grokcore.component.GlobalUtility):
+class CookbookServiceRootResource(ServiceRootResource):
     """A service root for the cookbook web service.
 
     Traversal to top-level resources is handled with the get() method.
     The top-level objects are stored in the top_level_names dict.
     """
     implements(IHasGet)
-    grokcore.component.provides(IServiceRootResource)
 
     @property
     def top_level_names(self):

=== modified file 'src/lazr/restful/example/base/traversal.py'
--- src/lazr/restful/example/base/traversal.py	2009-09-01 14:39:06 +0000
+++ src/lazr/restful/example/base/traversal.py	2009-09-03 14:04:03 +0000
@@ -4,7 +4,11 @@
 
 __metaclass__ = type
 __all__ = [
-    'TraverseWithGet']
+    'BelowRootAbsoluteURL',
+    'CookbookSetTraverse',
+    'RootAbsoluteURL',
+    'TraverseWithGet',
+    ]
 
 
 from urllib import unquote
@@ -13,21 +17,29 @@
 from zope.publisher.interfaces import IPublishTraverse, NotFound
 from zope.publisher.interfaces.browser import IDefaultBrowserLayer
 from zope.traversing.browser import absoluteURL, AbsoluteURL
-from zope.traversing.browser.interfaces import IAbsoluteURL
 
 import grokcore.component
 
 from lazr.restful.example.base.interfaces import ICookbookSet, IHasGet
 from lazr.restful.example.base.root import CookbookWebServiceObject
-from lazr.restful.interfaces import IWebServiceLayer
 from lazr.restful.simple import RootResourceAbsoluteURL
 from lazr.restful import RedirectResource
 
 
-# Grok setup of classes defined elsewhere.
-grokcore.component.global_adapter(RootResourceAbsoluteURL)
-grokcore.component.global_adapter(
-    AbsoluteURL, (CookbookWebServiceObject, IWebServiceLayer), IAbsoluteURL)
+class RootAbsoluteURL(RootResourceAbsoluteURL):
+    """A technique for generating the service's root URL.
+
+    This class contains no code of its own. It's defined so that grok
+    will pick it up.
+    """
+
+
+class BelowRootAbsoluteURL(AbsoluteURL):
+    """A technique for generating a root URL given an ILocation.
+
+    This class contains no code of its own. It's defined so that
+    grok will pick it up.
+    """
 
 
 class TraverseWithGet(grokcore.component.MultiAdapter):

=== modified file 'src/lazr/restful/example/wsgi/root.py'
--- src/lazr/restful/example/wsgi/root.py	2009-09-02 18:54:22 +0000
+++ src/lazr/restful/example/wsgi/root.py	2009-09-03 14:04:03 +0000
@@ -2,26 +2,34 @@
 
 __metaclass__ = type
 __all__ = [
+    'BelowRootAbsoluteURL',
+    'RootAbsoluteURL',
     'WebServiceConfiguration',
     'WSGIExampleWebServiceRootResource',
     ]
 
-import grokcore.component
-from zope.location.interfaces import ILocation
 from zope.traversing.browser import AbsoluteURL
-from zope.traversing.browser.interfaces import IAbsoluteURL
 
-from lazr.restful import directives
 from lazr.restful.example.wsgi.resources import (
     IKeyValuePair, PairSet, KeyValuePair)
-from lazr.restful.interfaces import IWebServiceLayer
 from lazr.restful.simple import (
     BaseWebServiceConfiguration, RootResource, RootResourceAbsoluteURL)
 
-# Grok setup of classes defined elsewhere.
-grokcore.component.global_adapter(RootResourceAbsoluteURL)
-grokcore.component.global_adapter(
-    AbsoluteURL, (ILocation, IWebServiceLayer), IAbsoluteURL)
+
+class RootAbsoluteURL(RootResourceAbsoluteURL):
+    """A technique for generating the service's root URL.
+
+    This class contains no code of its own. It's defined so that
+    grok will pick it up.
+    """
+
+
+class BelowRootAbsoluteURL(AbsoluteURL):
+    """A technique for generating a root URL given an ILocation.
+
+    This class contains no code of its own. It's defined so that
+    grok will pick it up.
+    """
 
 
 class WebServiceConfiguration(BaseWebServiceConfiguration):
@@ -41,4 +49,4 @@
             ]
         collections = dict(pairs=(IKeyValuePair, pairset))
         return collections, {}
-grokcore.component.global_utility(WSGIExampleWebServiceRootResource)
+